WhatsApp Gateway
API referenceWebhooks

Delete a webhook

Delete the webhook identified by `id`. Requires the `manage` capability, and the webhook must belong to the caller's organization. After deletion no further events are delivered to its url; any deliveries already pending retry stop. The deletion is permanent — there is no soft-delete (to pause deliveries without removing the config, set `active: false` via update instead). On success returns `204` with an empty body. Errors: `404 not_found` if no webhook with that id is owned by the caller's organization; `403 forbidden` if the caller lacks the `manage` capability.

DELETE
/api/v1/webhooks/{id}

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token>. The router accepts two kinds of token and tries each in turn: a frontend-minted login JWT (verified against the frontend JWKS; the person's org + role are read from it), or an api-key for a script/service (carrying a fixed set of gateway permissions). The bearerFormat: JWT label describes the person-login case.

In: header

Path Parameters

id*string

The webhook id. Must reference a webhook owned by the caller's organization, otherwise the request fails with a 404 "not_found".

Response Body

application/json

curl -X DELETE "https://example.com/api/v1/webhooks/01HHX5WEBHOOK..."
Empty
{  "error": {    "code": "not_found",    "details": {      "property1": null,      "property2": null    },    "message": "session not found"  }}

Update a webhook PATCH

Update the webhook identified by `id` — its `url`, `events`, `sessionId` scope, `secret`, `customHeaders`, `retryPolicy`, or `active` flag. Requires the `manage` capability, and the webhook must belong to the caller's organization. **Secret rotation.** Send a new `secret` to rotate it; omit the field to leave the stored secret unchanged. As elsewhere, the secret is never returned. On success returns `200` with the updated webhook. Errors: `404 not_found` if no webhook with that id is owned by the caller's organization; `422 validation_error` if the supplied fields are invalid (e.g. a malformed `url`); `403 forbidden` if the caller lacks the `manage` capability.