WhatsApp template webhook examples

For the exhaustive schema-derived catalog, see all examples.

What it is

Use the exact event type to distinguish template review, category, category-detection, and quality updates.

Before you begin

Create a public HTTPS endpoint in your application.
Configure a YCloud webhook endpoint for the event types you need.
Store the endpoint signing secret securely.
Make event processing idempotent.

How it works

YCloud sends an HTTP POST request when the event occurs. Verify the signature, durably record the event, return a 2xx response, and process slow work asynchronously.

Request

The scenarios below show requests delivered to your webhook URL. Treat the event id as the delivery identifier and use type to route the payload.

Response

Return a 2xx status after accepting the event.

HTTP/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see Configure webhooks.

Template Approved

In this case, your webhook endpoint received a template APPROVED event:

The template statusUpdateEvent is APPROVED.
The template status is now APPROVED.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "NONE",
    "statusUpdateEvent": "APPROVED"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Use wabaId, name, and language to identify the template in your system.
The statusUpdateEvent describes what happened on this template status, while the status is the current status of the template. They are not always the same.
This event occurs when a template is approved by Meta. The template can be the one you created or edited before. This also happens when a paused template changes to approved automatically.
Once a template is approved, you can use it to send template messages.

Template Rejected

In this case, your webhook endpoint received a template REJECTED event:

The template statusUpdateEvent is REJECTED.
The template status is now REJECTED.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "REJECTED",
    "reason": "SCAM",
    "statusUpdateEvent": "REJECTED"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

This event occurs when a template is rejected. The template can be the one you created or edited before.
Once a template is rejected, you cannot use it to send template messages. You can edit this template to start a new review.

Template Paused

In this case, your webhook endpoint received a template PAUSED event:

The template statusUpdateEvent is PAUSED.
The template status is now PAUSED.
The reason why the template is paused.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "PAUSED",
    "reason": "NONE",
    "statusUpdateEvent": "PAUSED"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

This event occurs when a template is paused. You cannot use it to send messages.
Pausing durations are as follows:
- 1st Instance: Paused for 3 hours
- 2nd Instance: Paused for 6 hours
- 3rd Instance: Disabled
A APPROVED event occurs when a paused template changes to normal status.
See also Template Pausing.

Template Flagged

In this case, your webhook endpoint received a template FLAGGED event:

The template statusUpdateEvent is FLAGGED.
The template status is now APPROVED.
Contains the date when the template will be disabled.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "Your WhatsApp message template has been paused for 3 hours until Feb 23 at 5:28 AM UTC because it had issues.",
    "statusUpdateEvent": "FLAGGED",
    "disableDate": "February 28, 2023"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

The statusUpdateEvent describes what happened on this template status, while the status is the current status of the template. They are not always the same.

Template Disabled

In this case, your webhook endpoint received a template DISABLED event:

The template statusUpdateEvent is DISABLED.
The template status is now DISABLED.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "DISABLED",
    "reason": "NONE",
    "statusUpdateEvent": "DISABLED"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

A template status changes to DISABLED at its 3rd pausing.
See also Template Pausing.

Template Pending Deletion

In this case, your webhook endpoint received a template PENDING_DELETION event:

The template statusUpdateEvent is PENDING_DELETION.
The template status is now DELETED.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "DELETED",
    "reason": "NONE",
    "statusUpdateEvent": "PENDING_DELETION"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Occurs when you delete a template.
The message template is being deleted. Remember that the name of this template can’t be used again for 30 days. You’ll need to use a different name to create new message templates.

Template Archived

In this case, your webhook endpoint received a template ARCHIVED event:

The template statusUpdateEvent is ARCHIVED.
The template status is now ARCHIVED.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "reason": "NONE",
    "statusUpdateEvent": "ARCHIVED"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

This event occurs when a template is archived.
Archived templates cannot be sent or edited.

Template Unarchived

In this case, your webhook endpoint received a template UNARCHIVED event:

The template statusUpdateEvent is UNARCHIVED.
The template status is the current status returned by Meta, for example APPROVED.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "NONE",
    "statusUpdateEvent": "UNARCHIVED"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

This event occurs when a template is unarchived.
The status may be APPROVED, but this event does not mean the template was newly approved by Meta.
Use statusUpdateEvent to distinguish UNARCHIVED from a real APPROVED review event.

Template category update

Use whatsapp.template.category_updated when a template category changes.

Request

{
  "id": "evt_example_whatsapp_template_category_updated",
  "type": "whatsapp.template.category_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "order_update",
    "language": "en_US",
    "previousCategory": "UTILITY",
    "category": "MARKETING"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Identify the template by officialTemplateId or by wabaId, name, and language. Compare previousCategory with the current category. previousCategory can be null for a newly created template; a category update is distinct from a review-status event.

Utility Direct Send category detection

Use whatsapp.template.correct_category_detection when Meta detects non-utility content in Utility Direct Send. Subscribe through the webhook endpoint API.

Request

{
  "id": "evt_direct_send_category_123",
  "type": "whatsapp.template.correct_category_detection",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "auto_generated_sample",
    "language": "en_US",
    "category": "MARKETING",
    "previousCategory": "UTILITY"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Read previousCategory and category to see the detected change. The exact event name is whatsapp.template.correct_category_detection, not whatsapp.template.category_updated. See Utility Direct Send for the integration workflow.

Template quality update

Use whatsapp.template.quality_updated when a template quality rating changes.

Request

{
  "id": "evt_example_whatsapp_template_quality_updated",
  "type": "whatsapp.template.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "order_update",
    "language": "en_US",
    "qualityRating": "GREEN"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Read qualityRating for the identified template. A quality event does not by itself indicate a new approval or rejection; handle review changes through whatsapp.template.reviewed.

​What it is

​Before you begin

​How it works

​Request

​Response

​Template Approved

​Request

​Response

​Explanation

​Template Rejected

​Request

​Response

​Explanation

​Template Paused

​Request

​Response

​Explanation

​Template Flagged

​Request

​Response

​Explanation

​Template Disabled

​Request

​Response

​Explanation

​Template Pending Deletion

​Request

​Response

​Explanation

​Template Archived

​Request

​Response

​Explanation

​Template Unarchived

​Request

​Response

​Explanation

​Template category update

​Request

​Response

​Explanation

​Utility Direct Send category detection

​Request

​Response

​Explanation

​Template quality update

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Template Approved

Request

Response

Explanation

Template Rejected

Request

Response

Explanation

Template Paused

Request

Response

Explanation

Template Flagged

Request

Response

Explanation

Template Disabled

Request

Response

Explanation

Template Pending Deletion

Request

Response

Explanation

Template Archived

Request

Response

Explanation

Template Unarchived

Request

Response

Explanation

Template category update

Request

Response

Explanation

Utility Direct Send category detection

Request

Response

Explanation

Template quality update

Request

Response

Explanation