Skip to content

Webhooks

Update a webhook

Changes whether the webhook is enabled and/or its shared token. The URL and signing secret cannot be changed; delete the webhook and create a new one instead. Send at least one field.

PATCH/api/v1/webhooks/{id}
  • Console only: owner or admin
  • Workspace: X-Tenant-ID

Path parameters

  • iduuidrequired

    Webhook id.

    Example
    708192a3-b4c5-4d6e-a7f8-091a2b3c4d5e

Headers

  • Cookiestringrequired

    The whatsappx_session cookie the app sets when you sign in. Browsers send it automatically; API keys are not accepted on this endpoint.

    Example
    whatsappx_session=…
  • X-Tenant-IDuuidrequired

    Workspace id. Required for session requests. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

application/json
  • enabledbooleanoptional

    Turn deliveries on or off.

    Example
    false
  • tokenstringoptional

    Set a new shared token (8–256 characters). An empty string removes it.

  • generate_tokenbooleanoptional

    Generate a new random whtok_ token.

    Default
    false
  • clear_tokenbooleanoptional

    Remove the shared token.

    Default
    false

Response

200 OKapplication/json

  • iduuid

    Webhook id.

  • urlstring

    HTTPS URL that receives deliveries.

  • eventsstring

    Always messages. It is informational and not a filter: every enabled webhook receives every event.

  • enabledboolean

    Whether deliveries are sent.

  • has_tokenboolean

    Whether a shared token is sent in X-Whatsappx-Webhook-Token.

  • created_atinteger

    Creation time in Unix seconds.

  • secretstringmay be absent

    Signing secret (whsec_ + 48 hex characters). Returned only in the create response; store it to verify X-Hub-Signature-256.

  • tokenstringmay be absent

    The shared token, returned only in the response that set or generated it. Generated tokens are whtok_ + 48 hex characters.

Status codes

  • 200OK. The updated webhook. token is included only when this request set or generated one; secret is never included.
  • 400Bad request. No change was requested (provide enabled and/or token changes), the token is invalid, the id is invalid (invalid webhook id) or the body is not JSON (invalid body).
  • 401Unauthorized. No signed-in session (unauthorized).
  • 403Forbidden. API keys can never call this endpoint (API keys cannot administer workspaces). A signed-in user who is not an owner or admin gets admin required; a user who is not a member of the workspace gets forbidden.
  • 404Not found. No webhook with this id in the workspace.

If you send more than one token option, clear_token wins over generate_token, which wins over token.