Skip to main content

​
What are Webhooks?

Webhooks allow you to receive real-time HTTP notifications when events occur in your Affonso affiliate program. Instead of polling our API for changes, webhooks push data to your server the moment something happens.

​
How Webhooks Work

  1. Event occurs - An affiliate signs up, a referral converts, a commission is paid, etc.
  2. Affonso sends a POST request - We send a JSON payload to your configured endpoint
  3. Your server processes the event - Handle the data as needed
  4. Respond with 200 OK - Confirm receipt of the webhook

​
Event Categories

Affiliate Events

Track when affiliates sign up, get approved, or update their details

Referral Events

Monitor referral clicks, leads, and conversions

Transaction Events

Get notified about sales, commissions, and refunds

Payout Events

Track affiliate payouts and payment status

​
Security

All webhook requests include a signature header for verification: 
X-Affonso-Signature: sha256=...
We sign each payload using HMAC-SHA256 with your webhook secret. Always verify this signature before processing webhook data.

​
Retry Policy

If your endpoint doesn’t respond with a 2xx status code, we’ll retry the webhook with exponential backoff:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
After 5 failed attempts, the webhook delivery is marked as failed.

​
Payload Structure

All webhook payloads follow a consistent structure: 
{
  "id": "evt_abc123",
  "type": "referral.converted",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    // Event-specific data
  }
}
FieldDescription
idUnique event identifier
typeThe event type (e.g., affiliate.created)
createdAtISO 8601 timestamp of when the event occurred
dataEvent-specific payload data

​
Next Steps

Set Up Webhooks

Configure webhook endpoints in your dashboard

Code Examples

Implementation examples in various languages