Webhooks

Webhook endpoints receive signed payout events. For the delivery model, signature verification, and best practices, see the Webhooks guide; for each event's payload, see Webhook events.

Create an endpoint

POST /v1/webhooks — Scope: webhooks:write

Registers an HTTPS endpoint and subscribes it to events. The response includes the signing secret, returned once — store it to verify deliveries.

Body parameters

Field	Type	Required	Description
`url`	string	Yes	Your endpoint. Must be `https://` with a host.
`events`	string[]	Yes	At least one event. Each must be one of the known events (below).

Subscribable events

payout.created
payout.processing
payout.completed
payout.failed
payout.blocked

Request

bash

curl https://api.caiboglobal.com/v1/webhooks \
  -H "X-API-Key: $CAIBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/caibo/webhook",
    "events": ["payout.completed", "payout.failed", "payout.blocked"]
  }'

Response — 201 Created

json

{
  "id": "whe_1a2b3c4d",
  "object": "webhook_endpoint",
  "url": "https://api.example.com/caibo/webhook",
  "events": ["payout.completed", "payout.failed", "payout.blocked"],
  "active": true,
  "secret": "whsec_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
  "created_at": "2026-07-23T14:03:00Z"
}

The secret is shown only in this response. Store it securely — you can't retrieve it again. If it's lost or leaked, delete the endpoint and create a new one.

Errors

HTTP	type	code	When
400	invalid_request_error	bad_request	A non-`https` or malformed `url`, no `events`, or an unknown event name.
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `webhooks:write`.
429	rate_limit_error	rate_limited	Too many requests.

List endpoints

GET /v1/webhooks — Scope: webhooks:read

Returns your registered endpoints. The signing secret is never returned on list.

bash

curl https://api.caiboglobal.com/v1/webhooks \
  -H "X-API-Key: $CAIBO_API_KEY"

Response — 200 OK

json

{
  "object": "list",
  "data": [
    {
      "id": "whe_1a2b3c4d",
      "object": "webhook_endpoint",
      "url": "https://api.example.com/caibo/webhook",
      "events": ["payout.completed", "payout.failed", "payout.blocked"],
      "active": true,
      "created_at": "2026-07-23T14:03:00Z"
    }
  ]
}

Errors

HTTP	type	code	When
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `webhooks:read`.
429	rate_limit_error	rate_limited	Too many requests.

Delete an endpoint

DELETE /v1/webhooks/{id} — Scope: webhooks:write

Deletes an endpoint. It stops receiving deliveries immediately. Returns 204 No Content.

bash

curl -X DELETE https://api.caiboglobal.com/v1/webhooks/whe_1a2b3c4d \
  -H "X-API-Key: $CAIBO_API_KEY"

Errors

HTTP	type	code	When
401	authentication_error	api_key_missing / api_key_invalid	No key, or an unknown/revoked key.
403	permission_error	scope_insufficient	The key lacks `webhooks:write`.
404	invalid_request_error	resource_missing	No such endpoint for your organization.