# 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

{% hint style="info" %}
Before starting this guide, make sure you have [API Access](https://docs.bird.com/api/api-access) and you are using the necessary Access Policies and Roles on your Access Key.
{% endhint %}

#### 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`    |

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

***

### 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

1. Navigate to **Developer App** > **Webhooks**
2. Click **Create webhook**
3. Enter your webhook **URL** (must be HTTPS and accessible from the internet)
4. Optionally enter a **Signing key** to verify webhook payloads
5. Under **Service**, select **Templates**
6. Select the **Event** you want to subscribe to (`template.created`, `template.updated`, or `template.deleted`)
7. 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**

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

```json
{
  "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. |

{% hint style="info" %}
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.
{% endhint %}

***

### Webhook Payload

When a template event occurs, Bird sends a POST request to your webhook URL with the following structure.

#### Envelope

```json
{
  "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`)           |

{% hint style="info" %}
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`.
{% endhint %}

***

### Example Payloads

#### template.created

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

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

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

1. **Verify the signature** using the `signingKey` you provided when creating the subscription
2. **Parse the payload** to extract the event type and template data
3. **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](https://docs.bird.com/api/channels-api/message-status-and-interactions).

***

### Platform-Specific Guides

For platform-specific details on template webhooks, including approval workflows and quality ratings:

* [WhatsApp Template Webhooks](/api/touchpoints-api/supported-projects/whatsapp-approved-message-templates/whatsapp-template-webhooks.md) -- Meta approval lifecycle, quality ratings (GREEN/YELLOW/RED), category tracking, and recommended actions for quality degradation

***

### Related Resources

* [Creating WhatsApp Message Templates](https://docs.bird.com/api/touchpoints-api/supported-projects/whatsapp-approved-message-templates/creating-whatsapp-message-templates) -- Full guide for creating WhatsApp templates
* [Webhook Subscriptions](https://docs.bird.com/api/notifications-api/api-reference/webhooks/create-a-webhook-subscription) -- Create and manage webhook subscriptions
* [Channel Events](https://docs.bird.com/api/channels-api/api-reference/events) -- Channel-level event reference


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/touchpoints-api/api-reference/message-templates/template-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.