Pular para o conteúdo principal
Webhooks de saída enviam eventos para uma URL que você controla, para que não seja preciso fazer polling na API REST em busca de novidades. Registre um endpoint uma vez e a iZap envia (via POST) cada evento assinado para ele assim que acontece — o Analytics MCP e a API REST são você chamando a iZap; aqui é a iZap chamando você.
Procurando o lado de entrada — o webhook da Cloud API da Meta que entrega mensagens do WhatsApp para a iZap? Esse é interno à conexão de WhatsApp da própria iZap. O que está nesta página é a entrega de saída da iZap para o seu endpoint.

Registrando um endpoint

url precisa ser https:// na porta padrão (443) — uma porta customizada (ex.: https://exemplo.com:8443/hook) é rejeitada, assim como um endereço privado ou de loopback, com 422. subscribed_events pode ficar [] para receber todos os eventos do catálogo, inclusive os que forem adicionados depois. A resposta é o único lugar em que o segredo de assinatura aparece por completo:
Guarde signing_secret imediatamente — não existe endpoint para lê-lo de volta depois. Se você o perder, gire-o para obter um novo.
Registrar um endpoint exige um plano que inclua webhooks de eventos. Sem isso, a chamada retorna 403 com code: "plan_limit_event_webhooks".
Um agente conectado ao MCP da iZap faz o mesmo com create_webhook_subscription, confere o estado das entregas com list_integrations e remove uma assinatura com delete_webhook_subscription. Pelo MCP, os eventos precisam ser escolhidos explicitamente; não existe a opção de lista vazia.

Catálogo de eventos

O catálogo é versionado apenas por adição — o formato dos eventos já publicados não muda, então analisar o message.received de hoje continua seguro conforme novos tipos de evento forem adicionados.

Payload

conversation.created

contact.phone é null para um visitante do chat do site, que não tem telefone. Neste evento conversation_id é sempre igual a chat.id, porque ele dispara para o chat que inicia a conversa. Os chats seguintes da mesma conversa, como a renovação da sessão de 24 horas, mantêm esse conversation_id e ganham seu próprio chat_id.

message.status_updated

error_code e error_reason só vêm preenchidos para estados de falha (failed ou undelivered). O corpo é serializado com chaves ordenadas e sem espaços extras, e é exatamente essa sequência de bytes que é assinada — verifique contra o corpo bruto da requisição, não contra um novo parse/serialização dele.

Cabeçalhos

Uma entrega reenviada (automática ou manualmente) carrega o mesmo izap-webhook-id e os mesmos bytes de payload, mas um novo izap-webhook-timestamp e ambas as assinaturas recalculadas no momento do envio. Só depois de verificar izap-webhook-signature-v2 é que izap-webhook-id é seguro como chave de idempotência — a v2 assina o próprio id, então uma entrega reenviada sob um id diferente falha na verificação. Deduplique pelo id somente depois dessa verificação, nunca pelo timestamp ou pela assinatura isoladamente: ambos mudam a cada nova tentativa e reenvio do mesmo evento.

Verificando a assinatura

izap-webhook-signature-v2 é a verificação recomendada — é a única das duas que cobre izap-webhook-id, o que fecha uma lacuna real: quem captura uma entrega pode reenviá-la dentro da sua tolerância de timestamp sob um izap-webhook-id novo, e uma verificação só com v1 continua válida, porque a v1 nunca assinou o id. Também não existe outro identificador assinado genérico no corpo para recorrer, e deduplicar por timestamp + assinatura não ajuda — ambos são recalculados a cada nova tentativa e reenvio do mesmo evento.
Leia o corpo como bytes brutos antes de qualquer parse de JSON automático do seu framework — a maioria dos frameworks armazena em buffer e re-codifica um corpo já processado, que deixa de bater com o que foi assinado.

Legado: assinatura v1

izap-webhook-signature (v1=<hex-hmac>) continua sendo enviada em toda entrega e não há plano de parar — integrações existentes continuam funcionando sem mudanças. Ela não cobre izap-webhook-id, então sozinha não distingue uma entrega reenviada sob um id novo de uma entrega genuinamente nova; prefira izap-webhook-signature-v2 em integrações novas, e migre as existentes quando for conveniente.

Entrega e novas tentativas

  • Seu endpoint tem 10 segundos para responder. Qualquer 2xx conta como entregue.
  • Respostas 5xx e 429 são reenviadas; qualquer outro 4xx é tratado como rejeição definitiva e não é reenviado — retorne 2xx somente depois de aceitar o evento de forma durável.
  • Depois de 20 falhas consecutivas um endpoint é desabilitado automaticamente (enabled: false, com last_error preenchido). Reative-o quando seu receptor estiver saudável novamente — ele não se recupera sozinho.

Gerenciando um endpoint

Toda requisição envia a empresa no header business-id, como no exemplo de cadastro acima. Girar o segredo invalida o anterior imediatamente — não há janela de sobreposição, então atualize seu código de verificação com o novo segredo antes de girar em produção. Um reenvio reproduz os bytes originais armazenados, então ele verifica contra o mesmo payload da primeira tentativa.

Monte um receptor

izap-wizard webhook receiver grava um ponto de partida que já implementa esse contrato para você.

Verifique com um SDK

webhooks.verify nos SDKs Python e TypeScript confere uma entrega contra o corpo cru da requisição. A CLI não recebe webhooks; use um SDK ou um receptor montado.