template.status

API reference/Webhook events

Copy page

template.status

Sent when WhatsApp reviews a template or changes its status. Use it to find out when a template you created is approved or rejected.

Called Template status changed in the app. Part of the plan feature webhooks.templates. To subscribe over the API, the key needs templates:read.

Delivered

{
  "id": "evt_287da8bc64eabe97c7a1a742c5ff191d",
  "type": "template.status",
  "api_version": "2026-10-14",
  "created_at": "2026-10-01T06:42:19.222Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "template": {
      "id": "2f9a6c1d-5e3b-4a78-8c04-b1d7e5f3a920",
      "name": "order_update",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "rejection_reason": null,
      "quality": "GREEN",
      "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
      "parameter_format": "positional",
      "header": {
        "format": "TEXT",
        "text": "Order {{1}}"
      },
      "body": "Hi {{1}}, your order {{2}} is on its way.",
      "footer": "Thanks for shopping with us",
      "buttons": [
        {
          "type": "URL",
          "text": "Track",
          "url": "https://example.com/track/{{1}}"
        }
      ],
      "variables": {
        "header": [
          "1"
        ],
        "body": [
          "1",
          "2"
        ],
        "buttons": {
          "0": [
            "1"
          ]
        }
      },
      "created_at": "2026-10-01T06:15:03.774Z",
      "updated_at": "2026-10-01T06:42:19.008Z"
    },
    "previous_status": "PENDING",
    "reason": null
  }
}

Show all 51 linesShow less

Headers

webhook-id

The delivery’s ID, the same on every try.

webhook-timestamp

When this try was sent, in Unix seconds.

webhook-signature

v1, and an HMAC-SHA256 of the request.

How delivery and retries work

Data

What’s in data. Every event wraps it in the same envelope.

template object

The template with its new status.

Show 16 child attributesHide child attributes

template.id string · uuid

template.name string

template.language string

template.category string

MARKETING, UTILITY or AUTHENTICATION, as WhatsApp has it. More values may be added.

template.status string

Where the template is in WhatsApp’s review: DRAFT (saved here, not submitted), PENDING, APPROVED, REJECTED, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION or DELETED. More values may be added. Only APPROVED templates can be sent.

template.rejection_reason string · nullable

WhatsApp’s reason, while the template is REJECTED. null otherwise.

template.quality string

WhatsApp’s quality rating: GREEN, YELLOW, RED or UNKNOWN. More values may be added.

template.number_id string · uuid · nullable

The number the template is on (see GET /v1/numbers).

template.parameter_format string

positional templates use {{1}}, {{2}} for variables; named ones use {{name}}.

template.header object · nullable

The header, or null if there is none.

Show 2 child attributesHide child attributes

template.header.format string

TEXT, or the format of a media header (IMAGE, VIDEO, DOCUMENT) or LOCATION on a template made in the app. More values may be added.

template.header.text string

The header text. Only on a TEXT header.

template.body string

template.footer string · nullable

template.buttons array of objects

Show 4 child attributesHide child attributes

Each item:

template.buttons[].type string

QUICK_REPLY, URL, PHONE_NUMBER or COPY_CODE, or another type of a template made in the app. More values may be added.

template.buttons[].text string

template.buttons[].url string

The link of a URL button. A {{1}} at the end is a variable.

template.buttons[].phone_number string

template.variables object

The exact variables a message that sends this template must supply (see POST /v1/messages). Positional templates use "1", "2"; named ones use the names. buttons is keyed by the button’s index in buttons, as a string. A URL button with a variable in its link needs "1", and so does a COPY_CODE button: its code is required every time you send the template.

Show 3 child attributesHide child attributes

template.variables.header array of strings

template.variables.body array of strings

template.variables.buttons object

A map; each value is an array of strings.

template.created_at string · date-time

template.updated_at string · date-time

previous_status string

The status it had before. The same values as template.status.

reason string · nullable

WhatsApp’s reason, such as why it was rejected. null when there isn’t one.

Handling it

• Answer with any 2xx within 10 seconds. Do the work after.
• Check the signature first. Verify webhooks has the code.
• Subscribe with POST /v1/webhooks, events: ["template.status"].