Webhooks

Webhooks allow you to receive real-time notifications when events occur in your account. Configure an endpoint URL and we'll send HTTP POST requests when events happen.

Event Types

Subscribe to the events that matter to your application:

Event	Description
`user.created`	A new user was created
`user.updated`	A user was updated
`user.deleted`	A user was deleted
`order.created`	A new order was placed
`order.paid`	An order payment was completed
`order.shipped`	An order was shipped
`order.delivered`	An order was delivered
`product.created`	A new product was created
`product.updated`	A product was updated

Payload Format

All webhook payloads follow this structure:

{
  "id": "evt_abc123",
  "type": "order.paid",
  "createdAt": "2024-01-25T16:00:00Z",
  "data": {
    "id": "ord_xyz789",
    "customerId": "usr_abc123",
    "total": 5998,
    "status": "paid"
  }
}

Verifying Webhooks

Each webhook includes a signature header that you should verify to ensure the request came from us:

webhook-handler.ts

1import crypto from 'crypto';
2
3function verifyWebhook(payload: string, signature: string, secret: string) {
4  const expectedSignature = crypto
5    .createHmac('sha256', secret)
6    .update(payload)
7    .digest('hex');
8  
9  return crypto.timingSafeEqual(
10    Buffer.from(signature),
11    Buffer.from(expectedSignature)
12  );
13}
14
15// In your webhook handler
16app.post('/webhooks', (req, res) => {
17  const signature = req.headers['x-webhook-signature'];
18  const isValid = verifyWebhook(
19    JSON.stringify(req.body),
20    signature,
21    process.env.WEBHOOK_SECRET
22  );
23  
24  if (!isValid) {
25    return res.status(401).send('Invalid signature');
26  }
27  
28  // Process the webhook
29  const { type, data } = req.body;
30  
31  switch (type) {
32    case 'order.paid':
33      // Handle paid order
34      break;
35    case 'user.created':
36      // Handle new user
37      break;
38  }
39  
40  res.status(200).send('OK');
41});

Important

Always verify webhook signatures before processing. This prevents attackers from sending fake events to your endpoint.

Webhook Endpoints

List Webhooks

GET/v1/webhooks

List all configured webhook endpoints.

Parameters

No parameters

Response

{
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/webhooks",
      "events": ["order.paid", "order.shipped"],
      "status": "active",
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ]
}

Create Webhook

POST/v1/webhooks

Create a new webhook endpoint.

Parameters

Name	Type	Required	Description
url	string	Required	The HTTPS URL to receive webhook events
events	array	Required	Array of event types to subscribe to

Request Body

{
  "url": "https://yourapp.com/webhooks",
  "events": ["order.paid", "order.shipped", "user.created"]
}

Response

{
  "data": {
    "id": "wh_new456",
    "url": "https://yourapp.com/webhooks",
    "events": ["order.paid", "order.shipped", "user.created"],
    "secret": "whsec_abc123xyz...",
    "status": "active",
    "createdAt": "2024-01-25T16:00:00Z"
  }
}

The webhook secret is only shown once when creating the webhook. Store it securely as you'll need it to verify incoming webhooks.

Delete Webhook

DELETE/v1/webhooks/:id

Delete a webhook endpoint.

Parameters

Name	Type	Required	Description
id	string	Required	The webhook ID to delete

Response

{
  "data": {
    "id": "wh_abc123",
    "deleted": true
  }
}