API referenceReference

Webhooks

The five events, how to verify one, and when we stop retrying.

What arrives

Register an endpoint on the Developers page and we POST to it when something happens on your account. This is how a payouts system finds out a creator earned something without polling for it.

Every delivery has the same envelope. The event's own fields are under data; everything outside it is the same on all five.

{
  "type": "conversion.attributed",
  "client": "4d6f8e21-...",
  "created": "2026-09-19T11:04:19.221Z",
  "data": { }
}

The five events

Five events. Each fires on a transition and never on a read, which matters more than it sounds: POST /v1/creators is called on every render of your own creator dashboard, so creator.enrolled fires only when a link is actually new. A page load is not a payout trigger.

  • creator.enrolled: A user of yours became a tracked creator and was issued a link. data carries campaignId, creator and link.

  • conversion.recorded: You reported a conversion and it was accepted. Your own receipt that we heard you, and it says nothing about whether anybody was credited. data carries conversionId, externalId, kind and occurredAt.

  • conversion.attributed: A conversion was credited to a creator, with a confidence tier. This is the one a payouts integration wants. data carries conversionId, accountId, linkId, confidence, tier and state.

  • conversion.reversed: A conversion was clawed back and its ledger entries undone. data carries conversionId, reversedMinor and whether it was the whole amount; the processor path also names the lifecycle, because a bank taking money back and a business returning it mean different things.

  • earning.locked: A creator's earning left its hold and can no longer be taken back. The signal to pay on: a creator's earning has left its hold and can no longer be taken back. data carries ledgerEntryId, creatorId, conversionId, attributionId, amountCents and currency.

  • fraud.finding: Monitoring raised something worth a person looking at. Only a finding that was not already open. data carries kind, severity, summary, detail and the subject it is about.

conversion.recorded and conversion.attributed are two events rather than one because they often have different answers. A sale can be recorded and credited to nobody, which is a normal outcome and not an error. Do not treat recorded as a signal to pay.

Neither fires on a replay. The idempotency key exists so you can retry a conversion safely, and a retry that produced a second webhook would make every careful caller the noisiest one.

Verifying a delivery

Your endpoint URL is public the moment it is configured, so verify the signature before you act on a delivery. The header is acrune-signature and carries a timestamp and an HMAC-SHA256, signed over the exact string `${t}.${body}`.

Node
import { createHmac, timingSafeEqual } from "node:crypto"

export function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((p) => p.trim().split("="))
  )
  const t = Number.parseInt(parts.t, 10)
  // A header that is not ours at all. Refuse it rather than throwing on it:
  // your endpoint is public and will be posted junk.
  if (!Number.isFinite(t) || typeof parts.v1 !== "string") return false
  // Five minutes, the same tolerance we refuse yours by.
  if (Math.abs(Date.now() / 1000 - t) > 300) return false
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex")
  const a = Buffer.from(expected)
  const b = Buffer.from(parts.v1)
  return a.length === b.length && timingSafeEqual(a, b)
}

Verify against the raw body, byte for byte. Parsing to JSON and re-serialising changes key order and whitespace, and the signature is over the bytes we sent rather than over the object they mean. Almost every failed integration of a scheme like this is this one mistake.

The timestamp is inside the hash so a captured delivery cannot be replayed at you later. We re-sign on every retry, so a delivery that arrives after a backoff is still inside the tolerance rather than being stale on arrival.

Retries, and when we give up

Answer 2xx and we stop. Three attempts happen inline, 400ms then 1.6s apart, each with a 4 second timeout so your slow endpoint never holds our own response open. After that a failed delivery waits in the background and is retried at 30 seconds, 5 minutes, 30 minutes, 2 hours and 6 hours.

Then it stops and keeps its error. An endpoint that has been down for a day is not coming back inside the usefulness of the event, and hammering it helps nobody. The row waits for a person, and the Developers page is where you see it.

A 4xx other than 429 is you saying no rather than saying later, so we do not retry it. Answer 429 if you are rate limited and 5xx if you are broken; answering 400 to a delivery you could not parse means you will never see it again.

Every attempt is recorded before it is made, with the exact body that was signed, so a delivery that dies before it can be attempted still leaves a trace. A webhook that failed silently is worse than one that failed, because your system is quietly out of step and nobody can say since when.

Subscribing, and what not to rely on

An endpoint with no event list subscribes to all five. Tick the ones you want on the Developers page to narrow it, and expect to receive an event you did not tick only if somebody widened the list.

Deliveries are best effort and never block the call that caused them. A conversion is not lost because your server is down, and a report from https://track.acrune.com/v1/reporting/summary is always the authority over a stream of events you may have missed.