Docs

Webhooks

Signed events for every change to partners, customers, transactions, commissions and payouts.

Add an https endpoint under Webhooks in the app and choose the events it receives. We POST each event as JSON:

{
  "id": "evt_…",
  "type": "commission.created",
  "created": 1793600000000,
  "program_id": "…",
  "data": { "object": "commission" }
}

Verifying the signature

Each request carries an Affiligato-Signature: t=1793600000,v1=… header. Compute HMAC-SHA256 of t + "." + rawBody with the endpoint’s signing secret, compare it to v1 in constant time, and reject a t more than five minutes old. With no dependency, in Node 20 or later, Deno, Bun or a Worker:

const verify = async (secret, header, rawBody) => {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '')
  if (!match || Math.abs(Date.now() - Number(match[1]) * 1000) > 300_000) return false
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { hash: 'SHA-256', name: 'HMAC' },
    false,
    ['verify']
  )
  const signature = new Uint8Array(match[2].match(/../g).map((pair) => parseInt(pair, 16)))

  return crypto.subtle.verify(
    'HMAC',
    key,
    signature,
    new TextEncoder().encode(`${match[1]}.${rawBody}`)
  )
}

Pass the body exactly as it arrived, before any JSON parsing.

Retries

Answer with any 2xx. Anything else is retried after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours. Every attempt is shown on the Webhooks page, where you can resend any delivery. Events can arrive more than once and out of order: use id to skip duplicates.

Events

Each event has its own page with an example payload: partner, referral, customer, link, transaction, commission and payout events.