Webhooks | Tusk WhatsApp API

Create a webhook

POST/v1/whatsapp/webhooks

Registers a URL for events. Returns the full secret once.

Body
Name	Type	Description
`url`required	string	Where to deliver events. Must be https on a public host.
`events`	string[]	Events to subscribe to, or `["*"]` for all. See the event list.
`secret`	string	16 to 100 characters. Generated if omitted. Signs each delivery in `X-Tusk-Signature`. Shown in full only on create and rotate.
`description`	string	A note for yourself.
`session_id`	string	Only deliver events of this session. Omit for all sessions.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/webhooks" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/whatsapp",
  "events": [
    "message.received",
    "message.ack"
  ],
  "description": "Order bot"
}'

201 Created

{
  "id": "5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31",
  "url": "https://example.com/hooks/whatsapp",
  "description": "Order bot",
  "events": [
    "message.received",
    "message.ack"
  ],
  "active": true,
  "session_id": null,
  "session_ref": null,
  "secret_preview": "whsec_ab...",
  "consecutive_failures": 0,
  "last_delivery_at": "2026-01-15T10:00:00Z",
  "last_status_code": 200,
  "created_at": "2026-01-15T09:35:00Z",
  "secret": "whsec_generated_once"
}

List webhooks

GET/v1/whatsapp/webhooks

Returns your webhooks.

curl "https://api.tuskmail.africa/v1/whatsapp/webhooks" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "data": [
    {
      "id": "5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31",
      "url": "https://example.com/hooks/whatsapp",
      "description": "Order bot",
      "events": [
        "message.received",
        "message.ack"
      ],
      "active": true,
      "session_id": null,
      "session_ref": null,
      "secret_preview": "whsec_ab...",
      "consecutive_failures": 0,
      "last_delivery_at": "2026-01-15T10:00:00Z",
      "last_status_code": 200,
      "created_at": "2026-01-15T09:35:00Z"
    }
  ]
}

Get a webhook

GET/v1/whatsapp/webhooks/{id}

Returns one webhook.

Parameters
Name	Type	Description
`id`required	path	The webhook id.

curl "https://api.tuskmail.africa/v1/whatsapp/webhooks/5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "id": "5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31",
  "url": "https://example.com/hooks/whatsapp",
  "description": "Order bot",
  "events": [
    "message.received",
    "message.ack"
  ],
  "active": true,
  "session_id": null,
  "session_ref": null,
  "secret_preview": "whsec_ab...",
  "consecutive_failures": 0,
  "last_delivery_at": "2026-01-15T10:00:00Z",
  "last_status_code": 200,
  "created_at": "2026-01-15T09:35:00Z"
}

Update a webhook

PUT/v1/whatsapp/webhooks/{id}

Changes a webhook. Send only the fields to change.

Parameters
Name	Type	Description
`id`required	path	The webhook id.
`url`	string	Where to deliver events. Must be https on a public host.
`events`	string[]	Events to subscribe to, or `["*"]` for all. See the event list.
`secret`	string	16 to 100 characters. Generated if omitted. Signs each delivery in `X-Tusk-Signature`. Shown in full only on create and rotate.
`description`	string	A note for yourself.
`session_id`	string	Only deliver events of this session. Omit for all sessions.
`active`	boolean	Pause or resume deliveries.

curl -X PUT "https://api.tuskmail.africa/v1/whatsapp/webhooks/5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    "*"
  ],
  "active": true
}'

200 OK

{
  "id": "5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31",
  "url": "https://example.com/hooks/whatsapp",
  "description": "Order bot",
  "events": [
    "*"
  ],
  "active": true,
  "session_id": null,
  "session_ref": null,
  "secret_preview": "whsec_ab...",
  "consecutive_failures": 0,
  "last_delivery_at": "2026-01-15T10:00:00Z",
  "last_status_code": 200,
  "created_at": "2026-01-15T09:35:00Z"
}

Delete a webhook

DELETE/v1/whatsapp/webhooks/{id}

Deletes a webhook.

Parameters
Name	Type	Description
`id`required	path	The webhook id.

curl -X DELETE "https://api.tuskmail.africa/v1/whatsapp/webhooks/5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31" \
  -H "X-API-Key: $TUSK_WA_KEY"

204 No Content

(empty body)

Send a test event

POST/v1/whatsapp/webhooks/{id}/test

Sends a signed webhook.test event and reports what your server answered.

Parameters
Name	Type	Description
`id`required	path	The webhook id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/webhooks/5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31/test" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "success": true,
  "status_code": 200,
  "error": null,
  "duration_ms": 142
}

List deliveries

GET/v1/whatsapp/webhooks/{id}/deliveries

Returns recent delivery attempts. The last 100 are kept.

Parameters
Name	Type	Description
`id`required	path	The webhook id.

curl "https://api.tuskmail.africa/v1/whatsapp/webhooks/5b0e9c3a-7d1f-4a62-9c1e-2f8a6d4b7e31/deliveries" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "data": [
    {
      "id": "d_1",
      "event": "message.received",
      "event_id": "evt_8f2c1a9d03b44e7a",
      "success": true,
      "status_code": 200,
      "attempts": 1,
      "duration_ms": 120,
      "error": null,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}