Skip to main content

​
What are template webhooks?

Unlike channel webhooks, offers template webhooks — endpoints that receive exclusively WhatsApp template events and do not depend on an instance (instanceId = null). They coexist with the per-channel webhook routes, which remain unchanged. Template event routing is handled by the internal service independently of any instance.
The concepts common to both webhook types (ENTERPRISE role, authentication, HMAC signing, and payload formats) are in the Introduction.

​
Authentication

All routes require the header:

​
Accepted template events

A template webhook accepts only template events. Sending any non-template event results in 422.

​
Business rules

  1. Event scope (required).
    • Template webhook → only accepts template events. Any non-template event → 422.
    • Channel webhook → cannot subscribe to template events → 422.
  2. payloadFormat is ignored. For template webhooks the format is always DEFAULT. The field may be omitted; if sent (any value, including CHATWOOT), it is silently discarded and persisted as DEFAULT.
  3. instanceId stored as null automatically — there is no instance field on these routes. channelId also comes back null.

​
Important notes

Per-tenant scope. Read/update/delete operations are scoped by the tenant resolved from the Authorization header — there is no cross-tenant access by id.
Router cache. After creating or updating a template webhook, routing may take up to ~5 min to reflect (cache TTL).

​
Management

Create template webhook

Register a new template endpoint.

List template webhooks

View all of the tenant’s template webhooks.

Get template webhook

Retrieve a specific template webhook.

Update template webhook

Update URL, events, authentication, or status.

Delete template webhook

Permanently remove a template webhook.

Payload structure

Real payload examples received for each template event.