Exemplos de webhooks de modelo do WhatsApp

Para o catálogo completo derivado do esquema, consulte todos os exemplos.

O que é

Use o evento exato type para distinguir atualizações de análise, categoria, detecção de categoria e qualidade de modelos.

Antes de começar

Crie um endpoint HTTPS público em sua aplicação.
Configure um endpoint de webhook da YCloud para os tipos de evento de que você precisa.
Armazene o segredo de assinatura do endpoint com segurança.
Torne o processamento de eventos idempotente.

Como funciona

A YCloud envia uma solicitação HTTP POST quando o evento ocorre. Verifique a assinatura, registre o evento de forma durável, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.

Solicitação

Os cenários abaixo mostram solicitações entregues à sua URL de webhook. Trate o id do evento como o identificador de entrega e use type para rotear o payload.

Resposta

Retorne um status 2xx após aceitar o evento.

HTTP/1.1 200 OK

Para configuração de endpoint, validação de assinatura e comportamento de novas tentativas, consulte Configurar webhooks.

Modelo aprovado

Neste caso, seu endpoint de webhook recebeu um evento de modelo APPROVED:

O statusUpdateEvent do modelo é APPROVED.
O status do modelo agora é APPROVED.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Use wabaId, name e language para identificar o modelo em seu sistema.
O statusUpdateEvent descreve o que aconteceu com o status deste modelo, enquanto o status é o status atual do modelo. Eles nem sempre são iguais.
Este evento ocorre quando um modelo é aprovado pela Meta. O modelo pode ser aquele que você criou ou editou anteriormente. Isso também acontece quando um modelo pausado muda automaticamente para aprovado.
Assim que um modelo for aprovado, você poderá usá-lo para enviar mensagens de modelo.

Modelo rejeitado

Neste caso, seu endpoint de webhook recebeu um evento de modelo REJECTED:

O statusUpdateEvent do modelo é REJECTED.
O status do modelo agora é REJECTED.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Este evento ocorre quando um modelo é rejeitado. O modelo pode ser aquele que você criou ou editou anteriormente.
Assim que um modelo for rejeitado, você não poderá usá-lo para enviar mensagens de modelo. Você pode editar esse modelo para iniciar uma nova análise.

Modelo pausado

Neste caso, seu endpoint de webhook recebeu um evento de modelo PAUSED:

O statusUpdateEvent do modelo é PAUSED.
O status do modelo agora é PAUSED.
O motivo pelo qual o modelo foi pausado.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Este evento ocorre quando um modelo é pausado. Você não pode usá-lo para enviar mensagens.
As durações da pausa são as seguintes:
- 1ª ocorrência: pausado por 3 horas
- 2ª ocorrência: pausado por 6 horas
- 3ª ocorrência: desativado
Um evento APPROVED ocorre quando um modelo pausado retorna ao status normal.
Consulte também Template Pausing.

Modelo sinalizado

Neste caso, seu endpoint de webhook recebeu um evento de modelo FLAGGED:

O statusUpdateEvent do modelo é FLAGGED.
O status do modelo agora é APPROVED.
Contém a data em que o modelo será desativado.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

O statusUpdateEvent descreve o que aconteceu com o status deste modelo, enquanto o status é o status atual do modelo. Eles nem sempre são iguais.

Modelo desativado

Neste caso, seu endpoint de webhook recebeu um evento de modelo DISABLED:

O statusUpdateEvent do modelo é DISABLED.
O status do modelo agora é DISABLED.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

O status de um modelo muda para DISABLED na sua 3ª pausa.
Consulte também Template Pausing.

Modelo com exclusão pendente

Neste caso, seu endpoint de webhook recebeu um evento de modelo PENDING_DELETION:

O statusUpdateEvent do modelo é PENDING_DELETION.
O status do modelo agora é DELETED.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Ocorre quando você exclui um modelo.
O modelo de mensagem está sendo excluído. Lembre-se de que o nome deste modelo não poderá ser usado novamente por 30 dias. Você precisará usar um nome diferente para criar novos modelos de mensagem.

Modelo arquivado

Neste caso, seu endpoint de webhook recebeu um evento de modelo ARCHIVED:

O statusUpdateEvent do modelo é ARCHIVED.
O status do modelo agora é ARCHIVED.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Este evento ocorre quando um modelo é arquivado.
Modelos arquivados não podem ser enviados nem editados.

Modelo desarquivado

Neste caso, seu endpoint de webhook recebeu um evento de modelo UNARCHIVED:

O statusUpdateEvent do modelo é UNARCHIVED.
O status do modelo é o status atual retornado pela Meta, por exemplo APPROVED.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Este evento ocorre quando um modelo é desarquivado.
O status pode ser APPROVED, mas este evento não significa que o modelo foi aprovado recentemente pela Meta.
Use statusUpdateEvent para distinguir UNARCHIVED de um evento real de análise APPROVED.

Atualização de categoria de modelo

Use whatsapp.template.category_updated quando a categoria de um modelo for alterada.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Identifique o modelo por officialTemplateId ou por wabaId, name e language. Compare previousCategory com o atual category. previousCategory pode ser nulo para um modelo recém-criado; uma atualização de categoria é diferente de um evento de status de análise.

Detecção de categoria do Utility Direct Send

Use whatsapp.template.correct_category_detection quando a Meta detectar conteúdo não relacionado à utilidade no Utility Direct Send. Assine por meio da API de endpoint de webhook.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Leia previousCategory e category para ver a alteração detectada. O nome exato do evento é whatsapp.template.correct_category_detection, não whatsapp.template.category_updated. Consulte Utility Direct Send para ver o fluxo de trabalho de integração.

Atualização de qualidade do modelo

Use whatsapp.template.quality_updated quando a classificação de qualidade de um modelo for alterada.

Solicitação

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

Resposta

Confirme a entrega após aceitar o evento de forma durável.

HTTP/1.1 200 OK

Explicação

Leia qualityRating para o modelo identificado. Um evento de qualidade não indica, por si só, uma nova aprovação ou rejeição; processe alterações de análise por meio de whatsapp.template.reviewed.

​O que é

​Antes de começar

​Como funciona

​Solicitação

​Resposta

​Modelo aprovado

​Solicitação

​Resposta

​Explicação

​Modelo rejeitado

​Solicitação

​Resposta

​Explicação

​Modelo pausado

​Solicitação

​Resposta

​Explicação

​Modelo sinalizado

​Solicitação

​Resposta

​Explicação

​Modelo desativado

​Solicitação

​Resposta

​Explicação

​Modelo com exclusão pendente

​Solicitação

​Resposta

​Explicação

​Modelo arquivado

​Solicitação

​Resposta

​Explicação

​Modelo desarquivado

​Solicitação

​Resposta

​Explicação

​Atualização de categoria de modelo

​Solicitação

​Resposta

​Explicação

​Detecção de categoria do Utility Direct Send

​Solicitação

​Resposta

​Explicação

​Atualização de qualidade do modelo

​Solicitação

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Solicitação

Resposta

Modelo aprovado

Solicitação

Resposta

Explicação

Modelo rejeitado

Solicitação

Resposta

Explicação

Modelo pausado

Solicitação

Resposta

Explicação

Modelo sinalizado

Solicitação

Resposta

Explicação

Modelo desativado

Solicitação

Resposta

Explicação

Modelo com exclusão pendente

Solicitação

Resposta

Explicação

Modelo arquivado

Solicitação

Resposta

Explicação

Modelo desarquivado

Solicitação

Resposta

Explicação

Atualização de categoria de modelo

Solicitação

Resposta

Explicação

Detecção de categoria do Utility Direct Send

Solicitação

Resposta

Explicação

Atualização de qualidade do modelo

Solicitação

Resposta

Explicação