Webhooks

Webhooks tell your server when something changes, so you can apply credit, send a thank-you email, or update your CRM. See every payload in the API reference.

Add an endpointCopy Anchor Link

In Settings → Webhooks, add your URL and choose events. Each endpoint gets its own signing secret, starting with whsec_.

Verify the signatureCopy Anchor Link

Every request includes a Referral-Signature header. Always check it before trusting the payload.

import { verifyWebhook } from '@referral-api/js/webhooks';

export async function POST(req: Request) {
  const event = verifyWebhook({
    payload: await req.text(),
    signature: req.headers.get('Referral-Signature')!,
    secret: process.env.REFERRAL_WEBHOOK_SECRET!,
  });

  if (event.type === 'reward.unlocked') {
    // apply credit in your billing system
  }

  return new Response(null, { status: 200 });
}

Example payloadCopy Anchor Link

{  "id": "evt_1Ab2Cd3E",  "type": "reward.unlocked",  "livemode": false,  "created_at": "2026-10-20T09:30:00Z",  "data": {    "id": "rwd_5Gh8kLq1",    "recipient": "referrer",    "amount": 2000,    "currency": "usd",    "status": "unlocked"  }}

RetriesCopy Anchor Link

If your endpoint doesn't return a 2xx status within 10 seconds, we retry with exponential backoff for up to three days. Retry $k$ waits roughly:

Use the event id to ignore duplicates, since an event can be delivered more than once.