Webhooks

Webhooks allow your application to receive real-time notifications from Buckaroo whenever important events occur—such as new sales, updates to transactions, or changes to customer or subscription data.

When one of your subscribed events happens, Buckaroo sends a push to the webhook URL you configured. Your system can then process the event and, if needed, retrieve additional details through the Buckaroo API.

1. Creating a Webhook Subscription

To register a webhook, send a POST request to the Webhooks API with the webhook configuration.

Example: Create a webhook subscription

{
  "url": "https://api.example.com/webhook",
  "storeId": "s_1234abcd",
  "eventTypes": [
    "sale.createdsale.create",
    "sale.updatedsale.update"
  ],
  "maxConcurrency": 10,
  "secret": "secretKey"
}

Field descriptions

Once saved, the webhook subscription becomes active immediately.

---

2. Managing Webhook Subscriptions

You can create, update, retrieve, and delete webhook subscriptions using standard CRUD operations.

➤ Retrieve all webhooks (GET)

GET /v1/webhooks Returns a list of webhook subscriptions configured for the authenticated merchant or app.

➤ Retrieve a single webhook (GET)

GET /v1/webhooks/{webhookId}

➤ Update an existing webhook (PATCH or POST)

PATCH /v1/webhooks/{webhookId}
POST /v1/webhooks

You can modify an existing subscription by sending updated fields:

{
  "eventTypes": ["sale.createdsale.create", "sale.updatedsale.update", "sale.refunded"],
  "maxConcurrency": 20
}

Only fields you include will be modified.

➤ Delete a webhook (DELETE)

DELETE /v1/webhooks/{webhookId}

This immediately disables the webhook and stops all deliveries.

---

3. Webhook Event Delivery

When one of the subscribed events occurs, Buckaroo sends a POST request to your url.

Example webhook payload

{
  "id": "evt_001",
  "type": "sale.createdsale.create",
  "createdAt": "2025-02-18T10:15:00Z",
  "data": {
    "saleId": "sa_9876def",
    "status": "pending"
  },
  "storeId": "s_1234abcd"
}

Important notes

• You receive only event metadata, not the full sale, subscription, or customer object.
• It is your responsibility to fetch the full resource from the API if your system requires the details.
• The secret you configured is used to verify authenticity of the request (depending on your signing mechanism).

4. Event Types

Each event type corresponds to a specific action. Examples:

5. Handling Webhooks on Your Side

Best practices

• Verify signatures using your webhook secret.
• Return 2xx responses as soon as possible—acknowledge receipt quickly.
• Avoid long-running operations in your webhook handler. If needed, enqueue processing in the background.
• Retry logic: Buckaroo will retry deliveries if your endpoint returns non-2xx responses.
• Use the event ID to avoid processing the same event twice.

6. Retrieving Full Data After a Webhook

Webhook payloads are intentionally lightweight. If you need the full sale/subscription/customer details:

1. Receive the event
2. Extract the relevant ID from data.
3. Call the Buckaroo API for the full resource:

GET /sales/{saleId}
Authorization: Bearer {access_token}

This pattern ensures reliability and security, even if webhook payloads are delayed or retried.

7. Summary

• Use webhooks for real-time notifications about important events.
• Register your webhook with POST /webhooks.
• Manage subscriptions with GET, PATCH, and DELETE.
• Webhooks deliver event metadata; you fetch full details through the API.
• Use your secret to verify authenticity and secure your integration.

---