Exemplos de webhook para conta e número de telefone do WhatsApp

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

O que é

Gerencie eventos de análise, atualização e exclusão de contas comerciais, além de exclusão de número de telefone, análise do nome de exibição, qualidade e atualizações do Business Username. Roteie cada payload pelo seu type exato de evento: eventos de conta usam whatsappBusinessAccount, enquanto eventos de número de telefone usam whatsappPhoneNumber.

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 requisição HTTP POST quando o evento ocorre. Verifique a assinatura, registre o evento de forma duradoura, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.

Requisição

Os cenários abaixo mostram requisiçõ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 endpoints, validação de assinatura e comportamento de novas tentativas, consulte Configurar webhooks.

Exclusão de conta

Use whatsapp.business_account.deleted para processar um evento de exclusão de conta do WhatsApp Business. Leia whatsappBusinessAccount.id para identificar a WABA afetada.

Requisição

{
  "id": "evt_business_account_deleted_123",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-26T12:00:00.000Z"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Os campos de remoção aparecem diretamente dentro de whatsappBusinessAccount quando disponíveis.

Campo	Significado
`id`	O ID da conta do WhatsApp Business afetada.
`removedReason`	O motivo bruto da remoção. Veja os valores conhecidos abaixo.
`removedInitiatedBy`	`USER` para remoção iniciada pelo usuário do WhatsApp, ou `SYSTEM` para remoção iniciada pela Meta.
`removedTime`	O momento em que a YCloud recebeu o evento de exclusão, no formato RFC 3339.

Os valores conhecidos de removedReason incluem:

Valor	Significado
`ACCOUNT_DISCONNECTED`	A conta foi desconectada devido a penalidades de conformidade ou porque a conta do WhatsApp foi excluída explicitamente.
`BUSINESS_DOWNGRADE`	O número de telefone foi registrado no aplicativo padrão do WhatsApp.
`CHANGE_NUMBER`	O número de telefone do WhatsApp foi alterado.
`COMPANION_INACTIVITY`	Um dispositivo complementar ficou inativo por aproximadamente 30 dias.
`PRIMARY_INACTIVITY`	Um dispositivo principal ficou inativo por aproximadamente 30 dias.
`USER_RE_REGISTERED`	O WhatsApp foi registrado novamente em um novo dispositivo.

Preserve valores desconhecidos de motivo e iniciador. Elimine duplicações de entregas pelo id do evento e tolere campos de remoção omitidos.

Authentication-International Rate Eligibility

A partir de 1º de junho de 2024, estamos introduzindo uma nova tarifa de autenticação internacional. Essa tarifa será aplicada nos seguintes países:

1º de junho de 2024 – Indonésia (código de discagem do país +62, código do país ID)
1º de julho de 2024 – Índia (código de discagem do país +91, código do país IN)

Para obter mais informações, consulte Authentication-International Rate Eligibility . Um webhook whatsapp.business_account.updated será disparado se a sua empresa for considerada elegível para tarifas internacionais. O webhook incluirá os horários de início para cada país que possua uma tarifa de autenticação internacional.

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Se uma mensagem for cobrada com a tarifa de autenticação internacional, o campo whatsappMessage.pricingCategory nos webhooks whatsapp.message.updated será definido como authentication_international. Aqui está um exemplo:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

Explicação

Roteie o evento por type, remova duplicatas por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.

Primary Business Location Update

Sua localização comercial principal é o país onde sua empresa está sediada. Ela aparecerá no Gerenciador de Negócios sob o campo Localização comercial principal a partir de 1º de maio de 2024. Se a Meta conseguir determinar o país onde sua empresa está sediada, dispararemos um webhook whatsapp.business_account.updated com o código de dois dígitos do país. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.

Atualização do limite de cadastro de números de telefone

A Meta envia uma atualização de capacidade de negócios para uma WABA quando o limite de cadastro de números de telefone do Portfólio empresarial ou da WABA correspondente é alterado. A YCloud a entrega como whatsapp.business_account.updated com updateEvent=BUSINESS_CAPABILITY_UPDATE. O webhook ocorre no nível da WABA: whatsappBusinessAccount.id é o ID da WABA da entrada do webhook da Meta. Atualmente, a Meta informa maxPhoneNumbersPerBusiness e maxPhoneNumbersPerWaba em atualizações separadas. Não os trate como mutuamente exclusivos: processe cada campo de forma independente e aceite ambos se uma atualização futura os incluir juntos. Um valor de 0 é válido. Aqui está um exemplo de uma atualização de limite de números de telefone da WABA:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e atualize apenas o campo de limite incluído no payload.

Violação de conta

Quando você receber um evento whatsapp.business_account.updated com whatsappBusinessAccount.updateEvent definido como ACCOUNT_VIOLATION, inspecione whatsappBusinessAccount.violationType para identificar a violação de política informada. Consulte Violações de aplicação de políticas da Meta para ver os tipos de violação e descrições. A Meta pode atualizar esta lista ao longo do tempo. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SCAM"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Restrição de conta

Se as contas do WhatsApp Business violarem repetidamente os Termos de Serviço do WhatsApp Business ou categorias de políticas de alto risco, como envio de spam, conteúdo adulto, venda de álcool e tabaco, drogas, jogos de azar e suplementos não seguros, elas poderão começar a sofrer restrições de mensagens que aumentam gradualmente de duração. Para o Utility Direct Send, consulte Notificações do Direct Send para ver um payload ACCOUNT_RESTRICTION da YCloud. Consulte Webhook para restrição de conta da Meta para obter detalhes de restrição e tipos de violação específicos do Direct Send. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      }
    ]
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Restrição do Utility Direct Send

Você recebe whatsapp.business_account.updated quando a Meta restringe o Utility Direct Send após o uso indevido recorrente da categoria. Este exemplo mostra uma restrição de sete dias.

Requisição

{
  "id": "evt_direct_send_restriction_123",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-24T08:00:00.000Z"
      }
    ]
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Use whatsappBusinessAccount.id para identificar a WABA afetada e pausar o fluxo de trabalho do Utility Direct Send. Leia violationType para saber o motivo, restrictions[].restrictionType para ver a funcionalidade afetada e restrictions[].expiration para conferir a data de expiração, quando fornecida. Uma análise bem-sucedida de um modelo não remove automaticamente uma restrição no nível da conta. Consulte Restrições e notificações do Direct Send.

Conta desativada

As contas do WhatsApp Business podem ser desativadas se a empresa não fizer alterações após vários avisos e limites ou bloqueios de recursos. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Restabelecimento de conta

Você pode recorrer da decisão de banimento da conta do WhatsApp Business para restabelecê-la. Uma vez aprovada, o status de análise da conta muda para APPROVED. Aqui está um exemplo:

Requisição

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Roteie o evento por type, remova duplicatas por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Análise de conta comercial

Use whatsapp.business_account.reviewed quando uma conta do WhatsApp Business tiver sido analisada.

Requisição

{
  "id": "evt_example_whatsapp_business_account_reviewed",
  "type": "whatsapp.business_account.reviewed",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "decision": "APPROVED",
    "accountReviewStatus": "APPROVED"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Identifique a WABA com id. Leia decision para conferir a decisão da análise (APPROVED ou REJECTED) e accountReviewStatus para o status de análise da conta quando fornecido. Não roteie este evento como whatsapp.business_account.updated.

Exclusão de número de telefone

Use whatsapp.phone_number.deleted quando um número de telefone comercial do WhatsApp for excluído.

Requisição

{
  "id": "evt_example_whatsapp_phone_number_deleted",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Use whatsappPhoneNumber.id para identificar o número de telefone excluído e wabaId para associá-lo à respectiva conta. Este é um evento de número de telefone; não o trate como a exclusão de toda a WABA.

Análise do nome de exibição do número de telefone

Use whatsapp.phone_number.name_updated quando o nome de exibição de um número de telefone comercial for aprovado ou rejeitado.

Requisição

{
  "id": "evt_example_whatsapp_phone_number_name_updated",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id",
    "verifiedName": "Example business",
    "requestedVerifiedName": "Example business",
    "decision": "APPROVED",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Leia decision e os campos de status do nome fornecidos. newNameStatus descreve a nova solicitação de nome de exibição, requestedVerifiedName identifica o último nome solicitado e rejectionReason descreve a rejeição quando houver. A análise do nome de exibição é separada de uma atualização de nome de usuário comercial.

Atualização da qualidade do número de telefone

Use whatsapp.phone_number.quality_updated para alterações no status relacionado à qualidade de um número de telefone comercial.

Requisição

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Leia qualityRating (GREEN, YELLOW ou RED) e qualityUpdateEvent para entender a atualização. messagingLimit é o nível do número de telefone; whatsappBusinessManagerMessagingLimit é o limite do portfólio empresarial proprietário. Mantenha esses campos separados e atualize apenas os valores fornecidos no evento.

Nome de usuário comercial ativado

Use whatsapp.phone_number.business_username_updated para sincronizar o nome de usuário comercial de um número de telefone.

Requisição

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

businessUsername é o nome de usuário ativo sem um @ inicial. Leia businessUsernameStatus e businessUsernameUpdatedAt com o id do número de telefone. Não confunda esse valor com o nome de exibição verificado.

Solicitação de nome de usuário comercial reservada

Um nome de usuário comercial ativo pode continuar em uso enquanto uma solicitação de substituição estiver reservada.

Requisição

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

HTTP/1.1 200 OK

Explicação

Neste exemplo, businessUsername permanece acme.support enquanto requestedBusinessUsername está acme.help. O status reserved descreve a solicitação pendente, não a ativação da substituição. Aceite o valor legado pending_review ao ler eventos mais antigos; novas gravações usam reserved.

​O que é

​Antes de começar

​Como funciona

​Requisição

​Resposta

​Exclusão de conta

​Requisição

​Resposta

​Explicação

​Authentication-International Rate Eligibility

​Requisição

​Resposta

​Explicação

​Primary Business Location Update

​Requisição

​Resposta

​Explicação

​Atualização do limite de cadastro de números de telefone

​Requisição

​Resposta

​Explicação

​Violação de conta

​Requisição

​Resposta

​Explicação

​Restrição de conta

​Requisição

​Resposta

​Explicação

​Restrição do Utility Direct Send

​Requisição

​Resposta

​Explicação

​Conta desativada

​Requisição

​Resposta

​Explicação

​Restabelecimento de conta

​Requisição

​Resposta

​Explicação

​Análise de conta comercial

​Requisição

​Resposta

​Explicação

​Exclusão de número de telefone

​Requisição

​Resposta

​Explicação

​Análise do nome de exibição do número de telefone

​Requisição

​Resposta

​Explicação

​Atualização da qualidade do número de telefone

​Requisição

​Resposta

​Explicação

​Nome de usuário comercial ativado

​Requisição

​Resposta

​Explicação

​Solicitação de nome de usuário comercial reservada

​Requisição

​Resposta

​Explicação

O que é

Antes de começar

Como funciona

Requisição

Resposta

Exclusão de conta

Requisição

Resposta

Explicação

Authentication-International Rate Eligibility

Requisição

Resposta

Explicação

Primary Business Location Update

Requisição

Resposta

Explicação

Atualização do limite de cadastro de números de telefone

Requisição

Resposta

Explicação

Violação de conta

Requisição

Resposta

Explicação

Restrição de conta

Requisição

Resposta

Explicação

Restrição do Utility Direct Send

Requisição

Resposta

Explicação

Conta desativada

Requisição

Resposta

Explicação

Restabelecimento de conta

Requisição

Resposta

Explicação

Análise de conta comercial

Requisição

Resposta

Explicação

Exclusão de número de telefone

Requisição

Resposta

Explicação

Análise do nome de exibição do número de telefone

Requisição

Resposta

Explicação

Atualização da qualidade do número de telefone

Requisição

Resposta

Explicação

Nome de usuário comercial ativado

Requisição

Resposta

Explicação

Solicitação de nome de usuário comercial reservada

Requisição

Resposta

Explicação