Skip to main content
Affixo can POST an event to your server whenever something happens in your program, a new affiliate, a conversion, a confirmed commission, a paid payout. Create endpoints from the dashboard (Settings → Webhooks) or via POST /v1/webhooks; each endpoint carries its own signing secret, returned once at creation.

Events

Every fulfilment.* payload has a source field that says why the reward was earned: conversion (a sale, with conversion_id), level (an affiliate moved up a tier, with level_change_id) or target (an affiliate hit a campaign target, with bonus_award_id). The ids for the other two sources are null. A reward that fired fulfilment.pending always ends with fulfilment.completed or fulfilment.cancelled. The cancelled payload’s reason says why: cancel_reason is null for the first two. A commission.reassigned payload carries from_affiliate_id (who held the commission before) and affiliate_id (who holds it now), plus the commission’s id, conversion_id, side (promoter, or sub_affiliate for a parent’s share), amount, currency and status, plus source and reassignment_id: You get one event per commission that changes hands, and its amount and status are unchanged. A parent’s share of the sale follows the new affiliate:
  • If both affiliates have a parent, the share moves to the new parent and you get a sub_affiliate event for it (none when it is the same parent).
  • If only the new affiliate has a parent, the share is new and its event has from_affiliate_id: null.
  • If only the original affiliate had a parent, the share is removed and no event is sent for it. When you get a promoter event with no sub_affiliate event for the same conversion_id, treat any parent share you hold for that sale as gone.
Moving a referral “from now on only” changes who future payments credit, so it sends nothing until those payments arrive. Paid commissions never move.

Payloads

Each delivery’s data object is one of the shapes below. Ids are UUIDs, timestamps are ISO 8601, and amounts are decimal numbers in the currency named next to them (99.5 with "currency": "usd" is $99.50). New fields can be added to any payload, so ignore the ones you don’t use.

affiliate.created

affiliate.updated

Sent once each time an affiliate’s status actually changes. Saving an affiliate without changing their status sends nothing. status is the affiliate’s status (pending, active, suspended, rejected and so on), except that an archived affiliate reads archived and one who left the program reads left. So the common changes look like this: The payload never says why a status changed.

affiliate.campaign_joined and affiliate.campaign_removed

via on affiliate.campaign_joined: via on affiliate.campaign_removed: A request to join a campaign that needs your approval sends nothing until you decide it. Deleting a campaign or an affiliate sends no affiliate.campaign_removed for the memberships that go with it.

conversion.created

conversion.reversed

commission.confirmed

commission.reversed

commission.reassigned

See the section above for source, reassignment_id and how a parent’s share moves.

customer.qualified

Sent once per customer, the first time one of their purchases earns an affiliate a confirmed commission. Later purchases by the same customer send nothing. A customer whose sale was blocked as a self-referral never qualifies.

payout.paid

fulfilment.pending, fulfilment.completed and fulfilment.cancelled

Test data

Test affiliates, test campaigns and Stripe test-mode sales never send webhooks, and neither does importing your program from another platform. Subscribe to specific events or ["*"] for everything (including any events added in the future). Unknown event names are rejected at creation time. The dashboard’s Send test button delivers a ping event. It bypasses your subscription filter, accept ping in your handler even if you validate the event name against the list above.

Delivery format

Each delivery is a POST with a JSON body:
Headers: Your endpoint must be https on a public host and should respond with a 2xx within 10 seconds. Redirects are treated as failures; respond at the subscribed URL directly.

Verifying signatures

The signature is an HMAC-SHA256 over "{timestamp}.{raw_body}" using your endpoint’s secret, hex-encoded, sent as X-Affixo-Signature: sha256=<hex>. Always verify against the raw request body (before any JSON parsing).
Node.js / Express
Rotating an endpoint’s secret (dashboard → Rotate) takes effect on the next delivery, deliveries are signed with the secret read at send time, so update your server first, then rotate.

Retries

Failed deliveries (non-2xx, timeout, or redirect) are retried with exponential backoff. Each delivery gets 6 attempts. After attempt n fails, the next one waits 4^n seconds: 4 seconds, then 16, 64, about 4 minutes and about 17 minutes. So a delivery that keeps failing is given up on roughly 25 minutes after the first try, and is marked failed. Because retries arrive minutes later, make your handler idempotent on X-Affixo-Delivery. Deliveries already queued keep their signing secret and URL resolution at send time, so a rotated secret or edited URL applies to every future attempt.

Delivery history

Every attempt is logged. In Settings → Webhooks, click View on a delivery to open its history: one row per attempt with when it ran, the HTTP status your endpoint returned (none if it never answered), how long it took, and a short error when it failed. The error is cleaned before it’s stored: query strings and credentials in URLs are stripped, anything that looks like a secret is replaced with [redacted], and it’s capped at 300 characters. Affixo never reads or stores your endpoint’s response body, so whatever your server sends back stays with you. Attempt history is kept for 30 days.

Resending a failed delivery

Once a delivery has used all its attempts and is marked failed, you can send it again from the dashboard: Settings → Webhooks, find the delivery in the list, and click Resend. It gets one more attempt, signed with the endpoint’s current secret and sent to its current URL, with the same X-Affixo-Delivery id and the same data as the original. Then use Process now to send it straight away instead of waiting for the next run. A few limits:
  • Only a delivery that has stopped retrying can be resent. One that went through, or is still being retried, can’t.
  • The endpoint has to be turned on.
  • You can resend the same delivery once every 10 minutes.
  • You need permission to manage security settings in the workspace.
Because a resend reuses the delivery id, a handler that deduplicates on X-Affixo-Delivery should only record an id once it has handled it successfully, or it will skip the resend.