API reference

Webhooks

Endpoints, signing secrets, deliveries and replay.

Base URL https://api.whabuzz.com. Every request needs Authorization: Bearer <key> unless the operation says otherwise; see Authentication. Errors follow the two-source contract.

Operations on this page:

GET /v1/webhooks: List endpoints
POST /v1/webhooks: Add an endpoint
GET /v1/webhooks/{endpoint_id}: Get an endpoint
PATCH /v1/webhooks/{endpoint_id}: Change URL, event types, description or status
DELETE /v1/webhooks/{endpoint_id}: Delete an endpoint
POST /v1/webhooks/{endpoint_id}/verify: Send the verify ping again
POST /v1/webhooks/{endpoint_id}/rotate-secret: Rotate the signing secret
POST /v1/webhooks/{endpoint_id}/replay: Re-send deliveries in a time range
GET /v1/webhook-deliveries: List deliveries
GET /v1/webhook-deliveries/{delivery_id}: Get a delivery with its attempt log
POST /v1/webhook-deliveries/{delivery_id}/replay: Re-send one delivery now

#List endpoints

GET/v1/webhooks

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: listWebhookEndpoints.

cURL:

curl -X GET "https://api.whabuzz.com/v1/webhooks" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Endpoints

{
  "data": [
    {
      "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
      "url": "https://api.example.com/whatsapp/events",
      "event_types": [
        "*"
      ],
      "status": "active",
      "verified_at": "2026-10-16T09:20:00Z",
      "secret_prefix": "whsec_Zm9v",
      "consecutive_failures": 0
    }
  ]
}

json

#Add an endpoint

POST/v1/webhooks

WhaBuzz sends a verify ping right away. Your endpoint must answer 2xx with the challenge (plain text, or JSON {"challenge":"…"}). Until an endpoint passes, your numbers are not connected. The signing secret is in this response only.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: createWebhookEndpoint.

Request body (application/json, required)

Field	Type	Required	Description
`url`	string (uri)	yes
`description`	string	no
`event_types`	array of * `or` message.inbound `or` message.status `or` message.error `or` message.echo `or` message.outbound `or` user.preferences `or` batch.completed `or` template.status `or` template.quality `or` template.category `or` number.quality `or` number.name `or` number.connection `or` account.update `or` account.alerts `or` account.capability `or` account.security `or` token.expiring `or` token.invalid `or` meta.other	no	Default `["*"]`.

Request example:

{
  "url": "https://api.example.com/whatsapp/events",
  "event_types": [
    "*"
  ]
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/webhooks" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/whatsapp/events",
  "event_types": [
    "*"
  ]
}'

bash

Responses

201 Created and verified

{
  "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "url": "https://api.example.com/whatsapp/events",
  "event_types": [
    "*"
  ],
  "status": "active",
  "verified_at": "2026-10-16T09:20:00Z",
  "secret": "whsec_Zm9vYmFyYmF6cXV4MTIzNDU2Nzg5MGFiY2RlZg",
  "secret_prefix": "whsec_Zm9v"
}

json

422 Created, but the verify ping failed. The endpoint stays pending; fix it and call verify.

{
  "source": "whabuzz",
  "error": {
    "code": "webhook_verify_failed",
    "message": "Endpoint answered 200 without the challenge",
    "details": {
      "endpoint_id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
      "http_status": 200,
      "body_excerpt": "OK",
      "secret": "whsec_Zm9vYmFyYmF6cXV4MTIzNDU2Nzg5MGFiY2RlZg"
    }
  },
  "request_id": "req_01JAB3W1Z4B7D0F3H6K9N2Q5S8"
}

json

#Get an endpoint

GET/v1/webhooks/{endpoint_id}

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: getWebhookEndpoint.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	path	string (uuid)	yes

cURL:

curl -X GET "https://api.whabuzz.com/v1/webhooks/$ENDPOINT_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Endpoint

{
  "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "url": "https://api.example.com/whatsapp/events",
  "description": "Production",
  "event_types": [
    "*"
  ],
  "status": "active",
  "verified_at": "2026-10-16T09:20:00Z",
  "secret_prefix": "whsec_Zm9v",
  "previous_secret_expires_at": null,
  "last_success_at": "2026-10-16T10:02:11Z",
  "consecutive_failures": 0
}

json

#Change URL, event types, description or status

PATCH/v1/webhooks/{endpoint_id}

Changing url re-runs the verify ping.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: updateWebhookEndpoint.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	path	string (uuid)	yes

Request body (application/json, required)

Request example:

{
  "event_types": [
    "message.inbound",
    "message.status"
  ],
  "status": "active"
}

json

cURL:

curl -X PATCH "https://api.whabuzz.com/v1/webhooks/$ENDPOINT_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "message.inbound",
    "message.status"
  ],
  "status": "active"
}'

bash

Responses

200 Updated

{
  "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "event_types": [
    "message.inbound",
    "message.status"
  ],
  "status": "active"
}

json

#Delete an endpoint

DELETE/v1/webhooks/{endpoint_id}

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: deleteWebhookEndpoint.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	path	string (uuid)	yes

cURL:

curl -X DELETE "https://api.whabuzz.com/v1/webhooks/$ENDPOINT_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Deleted

{
  "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "deleted": true
}

json

#Send the verify ping again

POST/v1/webhooks/{endpoint_id}/verify

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: verifyWebhookEndpoint.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	path	string (uuid)	yes

cURL:

curl -X POST "https://api.whabuzz.com/v1/webhooks/$ENDPOINT_ID/verify" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Passed

{
  "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "status": "active",
  "verified_at": "2026-10-16T09:25:00Z",
  "response_ms": 84
}

json

422 Failed

{
  "source": "whabuzz",
  "error": {
    "code": "webhook_verify_failed",
    "message": "Endpoint timed out after 5000 ms",
    "details": {
      "http_status": null
    }
  },
  "request_id": "req_01JAB3X2A5C8E1G4J7M0P3S6U9"
}

json

#Rotate the signing secret

POST/v1/webhooks/{endpoint_id}/rotate-secret

Both secrets sign every delivery until previous_secret_expires_at, so you can deploy the new one without dropping events.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: rotateWebhookSecret.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	path	string (uuid)	yes

Request body (application/json)

Field	Type	Required	Description
`overlap_hours`	integer	no	Default `24`. Range 0..168.

Request example:

{
  "overlap_hours": 24
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/webhooks/$ENDPOINT_ID/rotate-secret" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "overlap_hours": 24
}'

bash

Responses

200 New secret (shown once)

{
  "id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "secret": "whsec_bmV3c2VjcmV0MTIzNDU2Nzg5MGFiY2RlZmdoaQ",
  "secret_prefix": "whsec_bmV3",
  "previous_secret_expires_at": "2026-10-17T09:30:00Z"
}

json

#Re-send deliveries in a time range

POST/v1/webhooks/{endpoint_id}/replay

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: bulkReplay.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	path	string (uuid)	yes

Request body (application/json, required)

Field	Type	Required	Description
`from`	string (date-time)	yes
`to`	string (date-time)	yes
`status`	array of delivered `or` failed `or` dead	no	Default `["failed","dead"]`.
`event_types`	array of * `or` message.inbound `or` message.status `or` message.error `or` message.echo `or` message.outbound `or` user.preferences `or` batch.completed `or` template.status `or` template.quality `or` template.category `or` number.quality `or` number.name `or` number.connection `or` account.update `or` account.alerts `or` account.capability `or` account.security `or` token.expiring `or` token.invalid `or` meta.other	no

Request example:

{
  "from": "2026-10-16T00:00:00Z",
  "to": "2026-10-16T06:00:00Z",
  "status": [
    "dead"
  ]
}

json

cURL:

curl -X POST "https://api.whabuzz.com/v1/webhooks/$ENDPOINT_ID/replay" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-10-16T00:00:00Z",
  "to": "2026-10-16T06:00:00Z",
  "status": [
    "dead"
  ]
}'

bash

Responses

202 Queued

{
  "queued": 312
}

json

#List deliveries

GET/v1/webhook-deliveries

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: listDeliveries.

Parameters

Name	In	Type	Required	Description
`endpoint_id`	query	string (uuid)	no
`status`	query	`pending` or `delivered` or `failed` or `dead`	no
`event_id`	query	string	no
`from`	query	string (date-time)	no
`to`	query	string (date-time)	no
`limit`	query	integer	no
`cursor`	query	string	no	`next_cursor` from the previous page.

cURL:

curl -X GET "https://api.whabuzz.com/v1/webhook-deliveries" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Deliveries

{
  "data": [
    {
      "id": "dlv_01JAB3Y3B6D9F2H5K8N1Q4T7W0",
      "event_id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
      "event_type": "message.inbound",
      "endpoint_id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
      "status": "failed",
      "attempts": 3,
      "last_http_status": 503,
      "next_attempt_at": "2026-10-16T05:15:03Z"
    }
  ],
  "next_cursor": "dlv_01JAB3Y3B6D9F2H5K8N1Q4T7W0"
}

json

#Get a delivery with its attempt log

GET/v1/webhook-deliveries/{delivery_id}

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: getDelivery.

Parameters

Name	In	Type	Required	Description
`delivery_id`	path	string	yes

cURL:

curl -X GET "https://api.whabuzz.com/v1/webhook-deliveries/$DELIVERY_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 Delivery

{
  "id": "dlv_01JAB3Y3B6D9F2H5K8N1Q4T7W0",
  "event_id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "event_type": "message.inbound",
  "endpoint_id": "3c2b1a09-f8e7-4d6c-b5a4-9382716a5b4c",
  "status": "failed",
  "attempts": 3,
  "last_http_status": 503,
  "last_error": "http_5xx",
  "next_attempt_at": "2026-10-16T05:15:03Z",
  "attempt_log": [
    {
      "at": "2026-10-16T05:12:03Z",
      "http_status": null,
      "ms": 3000,
      "error": "timeout"
    },
    {
      "at": "2026-10-16T05:13:00Z",
      "http_status": 503,
      "ms": 41,
      "error": "http_5xx"
    },
    {
      "at": "2026-10-16T05:14:00Z",
      "http_status": 503,
      "ms": 38,
      "error": "http_5xx"
    }
  ],
  "is_replay": false
}

json

#Re-send one delivery now

POST/v1/webhook-deliveries/{delivery_id}/replay

One synchronous attempt with today's secrets. Works within your retention window.

Auth: API key (tenant key, or app key with X-WhaBuzz-Tenant). Operation id: replayDelivery.

Parameters

Name	In	Type	Required	Description
`delivery_id`	path	string	yes

cURL:

curl -X POST "https://api.whabuzz.com/v1/webhook-deliveries/$DELIVERY_ID/replay" \
  -H "Authorization: Bearer $WHABUZZ_KEY"

bash

Responses

200 The new delivery

{
  "id": "dlv_01JAB3Z4C7E0G3J6M9P2S5V8Y1",
  "status": "delivered",
  "attempts": 1,
  "last_http_status": 200,
  "last_response_ms": 92,
  "is_replay": true,
  "replay_of": "dlv_01JAB3Y3B6D9F2H5K8N1Q4T7W0"
}

json

404 Unknown delivery, or the event body is past retention

{
  "source": "whabuzz",
  "error": {
    "code": "not_found",
    "message": "Event body expired under the tenant's 90-day retention",
    "details": {
      "reason": "payload_expired"
    }
  },
  "request_id": "req_01JAB40A5D8F1H4K7N0Q3T6W9Z"
}

json

This page as Markdown: /api/webhooks.md. All docs in one file: /llms-full.txt.

Start

Guides

API reference

Webhook events

Reference

Webhooks

#List endpoints

#Add an endpoint

#Get an endpoint

#Change URL, event types, description or status

#Delete an endpoint

#Send the verify ping again

#Rotate the signing secret

#Re-send deliveries in a time range

#List deliveries

#Get a delivery with its attempt log

#Re-send one delivery now