Template Webhooks
Overview
Template webhooks provide real-time notifications when channel templates are created, updated, or deleted in your workspace. Use them to track template lifecycle changes -- including approval status, quality rating updates, and content changes.
Common use cases:
- Monitor template approval status changes (e.g., WhatsApp templates submitted to Meta)
- Track quality rating changes that affect messaging limits
- Get notified when templates move from draft to active
- Get notified when templates are deleted
Before starting this guide, make sure you have API Access and you are using the necessary Access Policies and Roles on your Access Key.
What templates are covered?
These webhooks apply to channel templates (project type channelTemplate) -- the templates used for platform-reviewed messaging such as WhatsApp approved templates. Channel templates can target the following platforms:
| Platform | platformId filter value |
|---|---|
| SMS | sms-messagebird |
| RCS | rcs-google |
| Facebook Messenger | facebook-messenger |
| Apple Business Chat | apple-business-chat |
| Line | line |
| Push Notifications | push-notifications |
HTML Email templates built with the dedicated email editor (project type htmlEmail) are a separate entity and are not covered by these webhooks. Template webhooks only fire for channel templates.
Currently, the platformInfo field (which includes category and qualityRating) is most relevant for WhatsApp templates, where Meta provides approval status and quality ratings. For other platforms, platformInfo may be empty or contain only a status field.
Supported Events
| Event | Description |
|---|---|
| template.created | A new channel template has been created |
| template.updated | A template has been updated (status change, content edit, etc.) |
| template.deleted | A template has been deleted |
Creating a Webhook Subscription
Template webhook subscriptions can be created through the Bird UI or the API.
Using the Bird UI
- Navigate to Developer App > Webhooks
- Click Create webhook
- Enter your webhook URL (must be HTTPS and accessible from the internet)
- Optionally enter a Signing key to verify webhook payloads
- Under Service, select Templates
- Select the Event you want to subscribe to (template.created, template.updated, or template.deleted)
- Optionally add an event filter for platformId to limit events to a specific platform (e.g., whatsapp)
Using the API
Create a webhook subscription by making a POST request to the webhooks endpoint.
POST /workspaces/{workspaceId}/webhooks
Example request
Ejemplo de código
{
"service": "templates",
"event": "template.updated",
"url": "https://your-server.com/webhooks/templates",
"signingKey": "your-signing-key"
}| Property | Required | Description |
|---|---|---|
| service | Yes | Must be templates |
| event | Yes | The event to subscribe to: template.created, template.updated, or template.deleted |
| url | Yes | Your webhook endpoint URL (must be HTTPS) |
| signingKey | No | A secret value used to verify that incoming webhook payloads are from Bird |
Filtering by platform
By default, a template webhook subscription receives events for all platforms. To limit events to a specific platform, add a platformId event filter:
Ejemplo de código
{
"service": "templates",
"event": "template.updated",
"url": "https://your-server.com/webhooks/templates",
"signingKey": "your-signing-key",
"eventFilters": [
{
"key": "platformId",
"value": "whatsapp"
}
]
}| Filter key | Description |
|---|---|
| platformId | The platform to filter by. See the supported platforms table for values. |
Event filters are inclusive. If you do not add a filter, you will receive events for all platforms. If you add a platformId filter, you will only receive events for that specific platform.
Webhook Payload
When a template event occurs, Bird sends a POST request to your webhook URL with the following structure.
Envelope
Ejemplo de código
{
"service": "templates",
"event": "template.created",
"payload": { ... }
}Payload fields
| Field | Type | Description |
|---|---|---|
| id | string (uuid) | The channel template ID |
| organizationId | string (uuid) | The organization ID |
| workspaceId | string (uuid) | The workspace ID |
| projectId | string (uuid) | The project ID that contains this template |
| name | string | The template name (extracted from deployments) |
| language | string | The template's default locale (e.g., en, en-US, pt-BR) |
| status | string | Template status: draft, pending, active, inactive, pendingReview |
| platformInfo | object | Per-platform state (status, category, quality rating). See below. |
| description | string | The template description, if set |
| createdAt | string (datetime) | When the template was created |
| updatedAt | string (datetime) | When the template was last updated |
platformInfo
The platformInfo field contains platform-specific state keyed by a composite identifier. For WhatsApp, keys follow the format whatsapp:{wabaId}:{locale}.
| Field | Type | Description |
|---|---|---|
| status | string | Platform-specific status: draft, active, inactive, pending, or pendingReview |
| category | string | Platform-specific category (e.g., UTILITY, MARKETING, AUTHENTICATION) |
| qualityRating | string | Platform-specific quality rating (e.g., GREEN, YELLOW, RED, UNKNOWN) |
Not all platforms use every field. For example, category and qualityRating are primarily relevant for WhatsApp templates, where Meta assigns categories and quality scores. For other platforms, these fields may be omitted or set to a default value like UNKNOWN.
Example Payloads
template.created
Ejemplo de código
{
"service": "templates",
"event": "template.created",
"payload": {
"id": "34dcb086-82c7-47f2-8939-7f0057def64e",
"organizationId": "8a2f4e10-3b5c-4d6e-9f8a-1b2c3d4e5f6a",
"workspaceId": "7c6d5e4f-3a2b-1c0d-9e8f-7a6b5c4d3e2f",
"projectId": "11323dfa-121f-4a4e-b4ef-35d325eaacb5",
"name": "order_confirmation",
"language": "en",
"status": "draft",
"description": "Order confirmation template",
"createdAt": "2025-09-20T09:11:46.28Z",
"updatedAt": "2025-09-20T09:11:46.28Z"
}
}template.updated
Ejemplo de código
{
"service": "templates",
"event": "template.updated",
"payload": {
"id": "34dcb086-82c7-47f2-8939-7f0057def64e",
"organizationId": "8a2f4e10-3b5c-4d6e-9f8a-1b2c3d4e5f6a",
"workspaceId": "7c6d5e4f-3a2b-1c0d-9e8f-7a6b5c4d3e2f",
"projectId": "11323dfa-121f-4a4e-b4ef-35d325eaacb5",
"name": "order_confirmation",
"language": "en",
"status": "active",
"platformInfo": {
"whatsapp:114128184961630:en": {
"status": "active",
"category": "UTILITY",
"qualityRating": "GREEN"
}
},
"createdAt": "2025-09-20T09:11:46.28Z",
"updatedAt": "2025-09-21T14:30:00.00Z"
}
}template.deleted
Ejemplo de código
{
"service": "templates",
"event": "template.deleted",
"payload": {
"id": "34dcb086-82c7-47f2-8939-7f0057def64e",
"organizationId": "8a2f4e10-3b5c-4d6e-9f8a-1b2c3d4e5f6a",
"workspaceId": "7c6d5e4f-3a2b-1c0d-9e8f-7a6b5c4d3e2f",
"projectId": "11323dfa-121f-4a4e-b4ef-35d325eaacb5",
"name": "order_confirmation",
"language": "en",
"status": "active",
"platformInfo": {
"whatsapp:114128184961630:en": {
"status": "active",
"category": "UTILITY",
"qualityRating": "GREEN"
}
},
"createdAt": "2025-09-20T09:11:46.28Z",
"updatedAt": "2025-10-01T12:00:00.00Z"
}
}Template Status Reference
| Status | Description |
|---|---|
| draft | Template has been created but not yet activated |
| pending | Template has been submitted for platform approval |
| active | Template is approved and available for sending |
| inactive | Template has been rejected, deactivated, or paused |
| pendingReview | Template is pending internal review (approval flows) |
Handling Webhooks
Your webhook endpoint should:
- Verify the signature using the signingKey you provided when creating the subscription
- Parse the payload to extract the event type and template data
- Take action based on the event and status:
- template.created -- Log or track new templates
- template.updated with status: "active" -- Template is ready for sending
- template.updated with status: "inactive" -- Template was rejected or paused; investigate
- template.deleted -- Stop using the template
Comparison with Channel Message Events
Template webhooks (templates service) track template lifecycle changes. Channel message webhooks (channels service) track individual message delivery and interactions. These are separate concerns:
| Use case | Service | Event |
|---|---|---|
| Template created/updated/deleted | templates | template.* |
| Message delivery status | channels | <channel>.outbound |
| Incoming message received | channels | <channel>.inbound |
| Message read/click/reaction | channels | <channel>.interaction |
For message delivery tracking, see Message status and interactions.
Platform-Specific Guides
For platform-specific details on template webhooks, including approval workflows and quality ratings:
- WhatsApp Template Webhooks -- Meta approval lifecycle, quality ratings (GREEN/YELLOW/RED), category tracking, and recommended actions for quality degradation
Related Resources
- Creating WhatsApp Message Templates -- Full guide for creating WhatsApp templates
- Webhook Subscriptions -- Create and manage webhook subscriptions
- Channel Events -- Channel-level event reference