Webhooks API

Programmatically manage webhook endpoints.

Use the Webhooks API to create, update, and manage your webhook endpoints programmatically.

GET/v1/webhooks

List all configured webhook endpoints.

Response

{
  "data": [
    {
      "id": "wh_xxxxx",
      "url": "https://api.yourapp.com/webhooks/referral",
      "events": ["referral.converted", "reward.earned"],
      "status": "active",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

POST/v1/webhooks

Create a new webhook endpoint.

Request Body

{
  "url": "https://api.yourapp.com/webhooks/referral",
  "events": ["referral.converted", "reward.earned"],
  "secret": "whsec_xxxxx"
}

Response

{
  "id": "wh_xxxxx",
  "url": "https://api.yourapp.com/webhooks/referral",
  "events": ["referral.converted", "reward.earned"],
  "secret": "whsec_xxxxx",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}

If you don't provide a secret, we'll generate one for you. Store it securely — you'll need it to verify webhook signatures.

DELETE/v1/webhooks/:id

Delete a webhook endpoint.

Parameters

Name	Type	Required	Description
id	string	Required	Webhook ID

Response

{
  "deleted": true
}

POST/v1/webhooks/:id/test

Send a test event to the webhook endpoint.

Parameters

Name	Type	Required	Description
id	string	Required	Webhook ID
eventType	string	Optional	Event type to test (default: referral.converted)

Response

{
  "sent": true,
  "responseStatus": 200,
  "responseTime": 145
}