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
WhatsApp	whatsapp
SMS	sms-messagebird
RCS	rcs-google
Facebook Messenger	facebook-messenger
Instagram	instagram
Apple Business Chat	apple-business-chat
Line	line
LinkedIn	linkedin
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

代码示例

{
  "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:

代码示例

{
  "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

代码示例

{
  "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

代码示例

{
  "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

代码示例

{
  "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

代码示例

{
  "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

Creating WhatsApp Message Templates -- Full guide for creating WhatsApp templates
Webhook Subscriptions -- Create and manage webhook subscriptions
Channel Events -- Channel-level event reference