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_affiliateevent 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
promoterevent with nosub_affiliateevent for the sameconversion_id, treat any parent share you hold for that sale as gone.
Payloads
Each delivery’sdata 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 aPOST with a JSON body:
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
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 waits4^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 sameX-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.
X-Affixo-Delivery should only record an id once it has handled it
successfully, or it will skip the resend.