Skip to content

Webhooks

Create a webhook

Adds a webhook that is enabled right away. The response contains the signing secret (and the token, if you set or generated one) only this once. A workspace can have at most 10 webhooks.

POST/api/v1/webhooks
  • Console only: owner or admin
  • Workspace: X-Tenant-ID

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
  • urlstringrequired

    Where deliveries are posted.

    Constraints
    https:// only, 12–2048 characters; localhost, 127.0.0.1, ::1 and *.local hosts are rejected.
    Example
    https://example.com/whatsappx/webhook
  • tokenstringoptional

    Optional shared token sent as X-Whatsappx-Webhook-Token on every delivery. Ignored when generate_token is true.

    Constraints
    8–256 characters, no line breaks.
  • generate_tokenbooleanoptional

    Generate a random token (whtok_ + 48 hex characters) instead of passing your own.

    Default
    false

Response

201 Createdapplication/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

  • 201Created. The new webhook, including secret (and token when set). Store them now: they are not shown again.
  • 400Bad request. Webhook URL must be at most 2048 characters, Enter a valid https:// URL, for example https://example.com/hooks/whatsapp, webhook URL must use https, localhost webhook URLs are not allowed, webhook token must be 8–256 characters, webhook token contains invalid characters, limit of 10 webhooks per workspace reached or 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.

What gets delivered, the headers and how to verify signatures are described in Webhooks and Webhook events.