Skip to main content

Webhooks

Webhooks send real-time HTTP POST notifications to your server when events occur in Affilync. Requires the webhooks:manage scope.

Create a Webhook​

curl -X POST https://api.affilync.com/api/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/affilync",
    "events": ["conversion.created", "call.completed"],
    "secret": "whsec_your_signing_secret"
  }'

Response (201):

{
  "id": "wh_e4f5g6",
  "url": "https://example.com/webhooks/affilync",
  "events": ["conversion.created", "call.completed"],
  "status": "active",
  "created_at": "2026-03-21T15:00:00Z"
}

Available Events​

EventTrigger
click.createdA tracking link is clicked
conversion.createdA new conversion is recorded
conversion.approvedA conversion is approved by the brand
conversion.rejectedA conversion is rejected
call.startedAn inbound call begins
call.completedA call ends (includes duration, outcome)
affiliate.appliedAn affiliate applies to your campaign
affiliate.approvedAn affiliate is approved
payout.completedA payout is successfully processed
campaign.updatedA campaign's settings are modified

Payload Format​

All webhook payloads follow this structure:

{
  "id": "evt_h7i8j9",
  "event": "conversion.created",
  "created_at": "2026-03-21T15:05:00Z",
  "data": {
    "conversion_id": "conv_j3k4l5",
    "campaign_id": "camp_abc123",
    "affiliate_id": "aff_m6n7o8",
    "type": "sale",
    "commission": "25.00",
    "order_value": "149.99"
  }
}

Signature Verification​

Every webhook request includes an X-Affilync-Signature header. Verify it to confirm the request is from Affilync:

X-Affilync-Signature: sha256=a1b2c3d4e5f6...

Compute the HMAC-SHA256 of the raw request body using your webhook secret and compare:

import hmac, hashlib

expected = hmac.new(
    key=b"whsec_your_signing_secret",
    msg=raw_body,
    digestmod=hashlib.sha256
).hexdigest()

assert hmac.compare_digest(f"sha256={expected}", signature_header)

Retry Policy​

If your endpoint returns a non-2xx status code or times out (30 second limit), Affilync retries:

AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry12 hours

After 5 failed retries, the event is marked as failed. View failed deliveries under Settings > Webhooks > [Webhook] > Deliveries.

Manage Webhooks​

MethodEndpointDescription
GET/api/webhooksList all webhooks
GET/api/webhooks/{id}Get webhook details
PATCH/api/webhooks/{id}Update URL or events
DELETE/api/webhooks/{id}Delete a webhook
GET/api/webhooks/{id}/deliveriesView delivery history
POST/api/webhooks/{id}/testSend a test event

Best Practices​

  • Always verify the signature before processing.
  • Respond with 200 OK quickly -- process the payload asynchronously.
  • Use the id field to deduplicate events (retries send the same event ID).
  • Monitor failed deliveries and fix endpoint issues promptly.

Next Steps​