API Reference

Webhooks

Every delivery is signed in the X-BoB-Signature header as t=<unix-ts>,v1=<hex>. To verify:

Reject if t is more than 5 minutes old (replay protection).
Compute HMAC-SHA256(secret, "<t>.<raw-body>") and hex-encode it.
Constant-time compare against v1.

During a secret rotation the header carries two v1= values (~24h overlap) — accept the delivery if either matches, so you can roll secrets with zero downtime.

GET/api/ext/v1/webhooks

List webhook endpoints

Responses

200Your organization's webhook endpoints — metadata only; signing secrets are shown once at create/rotate and never re-listed.

200 example

[
  {
    "created_at": "2026-01-15T09:30:00Z",
    "events": [
      "invoice.paid",
      "invoice.overdue"
    ],
    "id": "whk_5tQ8mR2x",
    "status": "active",
    "url": "https://example.com/webhooks/bob"
  }
]

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/webhooks \
  -H "Authorization: Bearer $BOB_API_TOKEN"

POST/api/ext/v1/webhooks

Create a webhook endpoint

Request body

Field	Type	Description
eventsoptional	string[]	Event types to subscribe to. Omit for all events.
urlrequired	string	Endpoint URL. Must be HTTPS and publicly routable.

Responses

201The endpoint plus its ONE-TIME signing secret (bok_whsec_…) — capture it now; it is never shown again.

Field	Type	Description
endpointrequired	WebhookEndpoint
secretrequired	string	One-time signing secret (bok_whsec_…). Shown once — capture it now.

201 example

{
  "endpoint": {
    "created_at": "2026-01-15T09:30:00Z",
    "events": [
      "invoice.paid",
      "invoice.overdue"
    ],
    "id": "whk_5tQ8mR2x",
    "status": "active",
    "url": "https://example.com/webhooks/bob"
  },
  "secret": "bok_whsec_EXAMPLE_not_a_real_secret"
}

Errors

400Invalid URL (must be HTTPS and publicly routable) or unknown event type

401Missing or invalid API token

403Token lacks the required scope or credential class

409Endpoint limit reached for your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl -X POST https://api.bankofbots.ai/api/ext/v1/webhooks \
  -H "Authorization: Bearer $BOB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "invoice.paid",
      "invoice.overdue"
    ],
    "url": "https://example.com/webhooks/bob"
  }'

GET/api/ext/v1/webhooks/{webhookId}

Get a webhook endpoint

Parameters

Name	In	Type	Description
webhookIdrequired	path	string	The webhook endpoint's id.

Responses

200The endpoint (no secret).

Field	Type	Description
created_atrequired	string · date-time	When the endpoint was created.
eventsrequired	string[]	Subscribed event types. Empty = all events in the catalog.
idrequired	string	The webhook endpoint id.
statusrequired	string	active, paused, or auto_disabled (after sustained failures).
urlrequired	string	HTTPS URL deliveries POST to.

200 example

{
  "created_at": "2026-01-15T09:30:00Z",
  "events": [
    "invoice.paid",
    "invoice.overdue"
  ],
  "id": "whk_5tQ8mR2x",
  "status": "active",
  "url": "https://example.com/webhooks/bob"
}

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such endpoint in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer $BOB_API_TOKEN"

PATCH/api/ext/v1/webhooks/{webhookId}

Update a webhook endpoint

Parameters

Name	In	Type	Description
webhookIdrequired	path	string	The webhook endpoint's id.

Request body

Field	Type
eventsoptional	string[]
statusoptional	string · nullable
urloptional	string · nullable

Responses

200The updated endpoint. Setting status active on an auto_disabled endpoint re-enables it.

Field	Type	Description
created_atrequired	string · date-time	When the endpoint was created.
eventsrequired	string[]	Subscribed event types. Empty = all events in the catalog.
idrequired	string	The webhook endpoint id.
statusrequired	string	active, paused, or auto_disabled (after sustained failures).
urlrequired	string	HTTPS URL deliveries POST to.

200 example

{
  "created_at": "2026-01-15T09:30:00Z",
  "events": [
    "invoice.paid",
    "invoice.overdue"
  ],
  "id": "whk_5tQ8mR2x",
  "status": "active",
  "url": "https://example.com/webhooks/bob"
}

Errors

400Invalid URL, unknown event type, or a status other than active/paused

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such endpoint in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl -X PATCH https://api.bankofbots.ai/api/ext/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer $BOB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "string"
    ],
    "status": "string",
    "url": "string"
  }'

DELETE/api/ext/v1/webhooks/{webhookId}

Delete a webhook endpoint

Parameters

Name	In	Type	Description
webhookIdrequired	path	string	The webhook endpoint's id.

Responses

204Deleted. In-flight deliveries to it are abandoned.

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such endpoint in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl -X DELETE https://api.bankofbots.ai/api/ext/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer $BOB_API_TOKEN"

GET/api/ext/v1/webhooks/{webhookId}/deliveries

List an endpoint's deliveries

Parameters

Name	In	Type	Description
webhookIdrequired	path	string	The webhook endpoint's id.

Responses

200Recent delivery attempts, newest first: status (pending/delivered/failed), attempt count, last response code, next retry time while pending.

200 example

[
  {
    "attempts": 1,
    "created_at": "2026-01-15T09:30:00Z",
    "event_id": "evt_2aQ9xL",
    "id": "whd_7bQ3nK",
    "last_error": "",
    "last_status_code": 200,
    "next_attempt_at": "2026-01-15T09:30:00Z",
    "status": "delivered"
  }
]

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such endpoint in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/webhooks/{webhookId}/deliveries \
  -H "Authorization: Bearer $BOB_API_TOKEN"

POST/api/ext/v1/webhooks/{webhookId}/rotate-secret

Rotate the signing secret

Parameters

Name	In	Type	Description
webhookIdrequired	path	string	The webhook endpoint's id.

Responses

200The NEW one-time secret. The previous secret keeps co-signing deliveries for 24 hours (a second v1 entry in X-BoB-Signature) so your fleet can roll.

Field	Type	Description
endpointrequired	WebhookEndpoint
secretrequired	string	The new one-time signing secret (bok_whsec_…). Shown once.

200 example

{
  "endpoint": {
    "created_at": "2026-01-15T09:30:00Z",
    "events": [
      "invoice.paid",
      "invoice.overdue"
    ],
    "id": "whk_5tQ8mR2x",
    "status": "active",
    "url": "https://example.com/webhooks/bob"
  },
  "secret": "bok_whsec_EXAMPLE_not_a_real_secret"
}

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such endpoint in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl -X POST https://api.bankofbots.ai/api/ext/v1/webhooks/{webhookId}/rotate-secret \
  -H "Authorization: Bearer $BOB_API_TOKEN"

POST/api/ext/v1/webhooks/{webhookId}/verify

Send a test event

Parameters

Name	In	Type	Description
webhookIdrequired	path	string	The webhook endpoint's id.

Responses

202Test event queued for THIS endpoint only. It arrives as a signed test.event delivery; check your receiver or the deliveries listing.

Field	Type	Description
delivery_idrequired	string	The delivery attempt's id — track it in the deliveries list.
event_idrequired	string	The test event's id.
statusrequired	string	Always "queued".

202 example

{
  "delivery_id": "whd_7bQ3nK",
  "event_id": "evt_2aQ9xL",
  "status": "queued"
}

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such endpoint in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl -X POST https://api.bankofbots.ai/api/ext/v1/webhooks/{webhookId}/verify \
  -H "Authorization: Bearer $BOB_API_TOKEN"

Was this page helpful?