Ejemplos de webhook para plantillas de WhatsApp

Para ver el catálogo exhaustivo derivado del esquema, consulta todos los ejemplos.

Qué es

Usa el evento exacto type para distinguir actualizaciones de revisión, categoría, detección de categoría y calidad de plantillas.

Antes de empezar

Crea un endpoint HTTPS público en tu aplicación.
Configura un endpoint de webhook de YCloud para los tipos de eventos que necesites.
Almacena el secreto de firma del endpoint de forma segura.
Haz que el procesamiento de eventos sea idempotente.

Cómo funciona

YCloud envía una solicitud HTTP POST cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, devuelve una respuesta 2xx y procesa las tareas lentas de forma asíncrona.

Solicitud

Los escenarios a continuación muestran solicitudes entregadas a la URL de tu webhook. Trata el evento id como el identificador de entrega y usa type para enrutar el payload.

Respuesta

Devuelve un estado 2xx tras aceptar el evento.

HTTP/1.1 200 OK

Para la configuración del endpoint, la validación de firmas y el comportamiento de reintentos, consulta Configurar webhooks.

Plantilla aprobada

En este caso, tu endpoint de webhook recibió un evento APPROVED de plantilla:

El valor statusUpdateEvent de la plantilla es APPROVED.
El valor status de la plantilla ahora es APPROVED.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Usa wabaId, name y language para identificar la plantilla en tu sistema.
El campo statusUpdateEvent describe qué ocurrió con el estado de esta plantilla, mientras que status es el estado actual de la plantilla. No siempre coinciden.
Este evento ocurre cuando Meta aprueba una plantilla. La plantilla puede ser la que creaste o editaste anteriormente. Esto también sucede cuando una plantilla pausada pasa a aprobada automáticamente.
Una vez aprobada una plantilla, puedes usarla para enviar mensajes de plantilla.

Plantilla rechazada

En este caso, tu endpoint de webhook recibió un evento REJECTED de plantilla:

El valor statusUpdateEvent de la plantilla es REJECTED.
El valor status de la plantilla ahora es REJECTED.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Este evento ocurre cuando se rechaza una plantilla. La plantilla puede ser la que creaste o editaste previamente.
Una vez rechazada una plantilla, no puedes usarla para enviar mensajes de plantilla. Puedes editar esta plantilla para iniciar una nueva revisión.

Plantilla pausada

En este caso, tu endpoint de webhook recibió un evento PAUSED de plantilla:

El valor statusUpdateEvent de la plantilla es PAUSED.
El valor status de la plantilla ahora es PAUSED.
El motivo por el cual la plantilla está pausada.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Este evento ocurre cuando se pausa una plantilla. No puedes usarla para enviar mensajes.
Las duraciones de la pausa son las siguientes:
- 1.ª instancia: pausada durante 3 horas
- 2.ª instancia: pausada durante 6 horas
- 3.ª instancia: inhabilitada
Se produce un evento APPROVED cuando una plantilla pausada vuelve al estado normal.
Consulta también Pausa de plantillas.

Plantilla marcada

En este caso, tu endpoint de webhook recibió un evento FLAGGED de plantilla:

El valor statusUpdateEvent de la plantilla es FLAGGED.
El estado de la plantilla ahora es APPROVED.
Contiene la fecha en la que se inhabilitará la plantilla.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

El campo statusUpdateEvent describe qué ocurrió con el estado de esta plantilla, mientras que status es el estado actual de la plantilla. No siempre coinciden.

Plantilla inhabilitada

En este caso, tu endpoint de webhook recibió un evento DISABLED de plantilla:

El valor statusUpdateEvent de la plantilla es DISABLED.
El estado de la plantilla ahora es DISABLED.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

El estado de una plantilla cambia a DISABLED en su tercera pausa.
Consulta también Pausa de plantillas.

Plantilla pendiente de eliminación

En este caso, tu endpoint de webhook recibió un evento PENDING_DELETION de plantilla:

El valor statusUpdateEvent de la plantilla es PENDING_DELETION.
El estado de la plantilla ahora es DELETED.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Ocurre cuando eliminas una plantilla.
La plantilla de mensaje se está eliminando. Recuerda que el nombre de esta plantilla no se podrá volver a usar durante 30 días. Deberás usar un nombre diferente para crear nuevas plantillas de mensaje.

Plantilla archivada

En este caso, tu endpoint de webhook recibió un evento ARCHIVED de plantilla:

El valor statusUpdateEvent de la plantilla es ARCHIVED.
El valor status de la plantilla ahora es ARCHIVED.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Este evento ocurre cuando se archiva una plantilla.
Las plantillas archivadas no se pueden enviar ni editar.

Plantilla desarchivada

En este caso, tu endpoint de webhook recibió un evento UNARCHIVED de plantilla:

El valor statusUpdateEvent de la plantilla es UNARCHIVED.
El valor status de la plantilla es el estado actual devuelto por Meta, por ejemplo APPROVED.

Solicitud

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"
  }
}'

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Este evento ocurre cuando se desarchiva una plantilla.
El valor de status puede ser APPROVED, pero este evento no significa que la plantilla haya sido aprobada recientemente por Meta.
Usa statusUpdateEvent para distinguir UNARCHIVED de un evento real de revisión APPROVED.

Actualización de categoría de plantilla

Usa whatsapp.template.category_updated cuando cambie la categoría de una plantilla.

Solicitud

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

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Identifica la plantilla mediante officialTemplateId o mediante wabaId, name y language. Compara previousCategory con el valor actual de category. previousCategory puede ser null para una plantilla recién creada; una actualización de categoría es distinta de un evento de estado de revisión.

Detección de categoría de Utility Direct Send

Usa whatsapp.template.correct_category_detection cuando Meta detecte contenido que no sea de utilidad en Utility Direct Send. Suscríbete mediante la API de endpoints de webhook.

Solicitud

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

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Consulta previousCategory y category para ver el cambio detectado. El nombre exacto del evento es whatsapp.template.correct_category_detection, no whatsapp.template.category_updated. Consulta Utility Direct Send para ver el flujo de trabajo de integración.

Actualización de calidad de plantilla

Usa whatsapp.template.quality_updated cuando cambie la calificación de calidad de una plantilla.

Solicitud

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

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Consulta qualityRating para la plantilla identificada. Un evento de calidad no indica por sí mismo una nueva aprobación o rechazo; gestiona los cambios de revisión a través de whatsapp.template.reviewed.

​Qué es

​Antes de empezar

​Cómo funciona

​Solicitud

​Respuesta

​Plantilla aprobada

​Solicitud

​Respuesta

​Explicación

​Plantilla rechazada

​Solicitud

​Respuesta

​Explicación

​Plantilla pausada

​Solicitud

​Respuesta

​Explicación

​Plantilla marcada

​Solicitud

​Respuesta

​Explicación

​Plantilla inhabilitada

​Solicitud

​Respuesta

​Explicación

​Plantilla pendiente de eliminación

​Solicitud

​Respuesta

​Explicación

​Plantilla archivada

​Solicitud

​Respuesta

​Explicación

​Plantilla desarchivada

​Solicitud

​Respuesta

​Explicación

​Actualización de categoría de plantilla

​Solicitud

​Respuesta

​Explicación

​Detección de categoría de Utility Direct Send

​Solicitud

​Respuesta

​Explicación

​Actualización de calidad de plantilla

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de empezar

Cómo funciona

Solicitud

Respuesta

Plantilla aprobada

Solicitud

Respuesta

Explicación

Plantilla rechazada

Solicitud

Respuesta

Explicación

Plantilla pausada

Solicitud

Respuesta

Explicación

Plantilla marcada

Solicitud

Respuesta

Explicación

Plantilla inhabilitada

Solicitud

Respuesta

Explicación

Plantilla pendiente de eliminación

Solicitud

Respuesta

Explicación

Plantilla archivada

Solicitud

Respuesta

Explicación

Plantilla desarchivada

Solicitud

Respuesta

Explicación

Actualización de categoría de plantilla

Solicitud

Respuesta

Explicación

Detección de categoría de Utility Direct Send

Solicitud

Respuesta

Explicación

Actualización de calidad de plantilla

Solicitud

Respuesta

Explicación