Webhooks Overview

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

Event occurs - An affiliate signs up, a referral converts, a commission is paid, etc.
Affonso sends a POST request - We send a JSON payload to your configured endpoint
Your server processes the event - Handle the data as needed
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 and commissions. Refunds are not a separate event: a full refund arrives as transaction.rejected, a partial refund as transaction.updated.

Payout Events

Track affiliate payouts and payment status

Security

All webhook requests include two headers for verification:

X-Affonso-Timestamp: 1704067200
X-Affonso-Signature: 4f2c8a1b9d3e7f0a6c5b8d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a

Affonso signs the string {timestamp}.{rawBody} with HMAC-SHA256 using your endpoint secret and sends the lowercase hex digest, without any prefix, in X-Affonso-Signature. The timestamp is sent in X-Affonso-Timestamp. Reject requests older than 5 minutes. See Webhook Setup for verification examples.

Retry Policy

If your endpoint returns a non-2xx status code or does not respond within 10 seconds, the delivery is treated as failed. Affonso retries with exponential backoff for up to 48 hours, 11 attempts total. After that, the 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
  }
}

Field	Description
`id`	Unique event identifier
`type`	The event type (e.g., `affiliate.created`)
`createdAt`	ISO 8601 timestamp of when the event occurred
`data`	Event-specific payload data

Overview

Events

Usage & Examples

Automation Tools

What are Webhooks?

How Webhooks Work

Event Categories

Affiliate Events

Referral Events

Transaction Events

Payout Events

Security

Retry Policy

Payload Structure

Next Steps

Set Up Webhooks

Code Examples

​What are Webhooks?

​How Webhooks Work

​Event Categories

Affiliate Events

Referral Events

Transaction Events

Payout Events

​Security

​Retry Policy

​Payload Structure

​Next Steps

Set Up Webhooks

Code Examples

What are Webhooks?

How Webhooks Work

Event Categories

Security

Retry Policy

Payload Structure

Next Steps