Skip to main content
Webhooks let your backend react to AgentRef events without polling the API. When something interesting happens – an affiliate joins, a conversion is created, a payout completes – AgentRef sends an HTTP POST to your endpoint with a signed JSON payload.

​
How it works

  1. You register an HTTPS endpoint (your server URL)
  2. You choose which event types to subscribe to
  3. AgentRef sends a signed POST request to your URL every time a matching event fires
  4. Your server responds with a 2xx status to acknowledge receipt
  5. If delivery fails, AgentRef retries automatically on an exponential backoff schedule

​
Webhook envelope

Every webhook delivery shares the same outer envelope regardless of event type: 
{
  "id": "msg_01jq2k3n4p5q6r7s8t9u0v1w2x",
  "type": "conversion.created",
  "schemaVersion": 2,
  "createdAt": "2026-03-15T14:22:00.000Z",
  "merchantId": "mch_01jq2abc",
  "programId": "prg_01jq2def",
  "environment": "production",
  "data": { ... }
}
FieldDescription
idUnique message ID. Use this for idempotency.
typeEvent type string, e.g. conversion.created
schemaVersionAlways 2 for current payloads
createdAtISO 8601 timestamp when the event was created
merchantIdYour merchant ID
programIdProgram ID the event belongs to (omitted for merchant-scoped events)
environmentproduction, preview, or development
dataEvent-specific payload (see Events)

​
Registering a webhook endpoint

  1. Go to Settings → Webhooks in your dashboard
  2. Click Add endpoint
  3. Enter your endpoint URL and a descriptive name
  4. Select the event types you want to receive
  5. Optionally scope the endpoint to a specific program
  6. Click Create – your signing secret is shown once; copy it now

​
Event type filtering

You must subscribe to at least one event type per endpoint. You can subscribe to any subset of the 13 available events. Only events in your subscription list will be delivered to that endpoint. To update subscriptions on an existing endpoint:
cURL
curl -X PATCH https://www.agentref.co/api/v1/webhooks/wh_01jq2k3n \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"subscribedEvents": ["conversion.created", "conversion.refunded", "payout.completed"]}'

​
Program scoping

By default, a webhook endpoint receives events from all your programs. If you have multiple programs and want to isolate events, you can scope an endpoint to a specific program by passing programId when creating or updating the endpoint. A scoped endpoint only receives events where programId matches. Unscoped endpoints receive events from every program.
cURL
curl -X POST https://www.agentref.co/api/v1/webhooks \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Program A only",
    "url": "https://your-app.com/webhooks/program-a",
    "subscribedEvents": ["affiliate.joined"],
    "programId": "prg_01jq2def"
  }'

​
Endpoint requirements

  • HTTPS only – HTTP endpoints are rejected in production (localhost HTTP is allowed during development)
  • Respond within 30 seconds – requests that time out are treated as failed deliveries
  • Return a 2xx status – any non-2xx response triggers a retry, including 3xx redirects
  • No authentication required on your side – verify the request using the signature instead

​
Managing endpoints via API

MethodPathScope requiredDescription
GET/api/v1/webhookswebhooks:readList all endpoints
POST/api/v1/webhookswebhooks:writeCreate an endpoint
GET/api/v1/webhooks/{id}webhooks:readGet a single endpoint
PATCH/api/v1/webhooks/{id}webhooks:writeUpdate name, URL, or subscriptions
DELETE/api/v1/webhooks/{id}webhooks:writeDisable an endpoint
POST/api/v1/webhooks/{id}/rotate-secretwebhooks:writeRotate the signing secret
Deleting an endpoint marks it as disabled. Disabled endpoints stop receiving deliveries and cannot be re-enabled via API – create a new endpoint instead.

​
Next steps

Signature Verification

Verify incoming requests are genuinely from AgentRef

Events Reference

Full payload examples for all 13 event types

Retry & Delivery

Understand retries, idempotency, and failure handling

Testing

Test your endpoint locally before going to production