Webhooks (saída)
Configure em Integrações → Acesso à API → Webhooks (session,workspaces:manage).
O Flow envia POST JSON. Valide a assinatura X-Flow-Signature (HMAC-SHA256 do corpo bruto).
Requisitos da URL
Em qualquer ambiente o Flow rejeita
localhost, 127.0.0.1, redes privadas e metadata cloud. Redirects HTTP durante a entrega não são seguidos. HTTPS nunca ignora erros de certificado.
Exemplo (Sandbox, HTTP público)
Testar na sua máquina local
O Flow não consegue alcançarhttp://localhost:... nem IPs da sua LAN — esses endereços só existem na sua rede. Para desenvolver localmente, exponha o endpoint com um túnel HTTPS público, por exemplo:
Registre a URL pública gerada pelo túnel (em produção ela deve ser HTTPS).
Eventos
Envelope
hex = HMAC-SHA256(secret, raw_body) — use os bytes brutos do JSON recebido, sem re-serializar.
Falhas retentam com backoff; após falhas sustentadas o webhook pode ser desativado (active=false).
As entregas têm semântica at-least-once. Use data.id ou data.provider_message_id para deduplicar no sistema consumidor.
Diagnóstico de falhas
Em Integrações → Acesso à API → Webhooks → Últimas entregas, o Flow mostra cada tentativa, o status HTTP e uma recomendação. Quando o diagnóstico confirma que a falha está no endpoint configurado, a interface indica o ajuste necessário. Em causas desconhecidas, o diagnóstico permanece neutro para investigação conjunta.
O Flow mantém a validação TLS em HTTPS. Não é seguro ignorar erros de certificado: isso poderia enviar dados a um servidor que não comprova ser o domínio configurado. No Sandbox, prefira HTTP público explícito se ainda não tiver certificado válido.
Mensagens WhatsApp
Os eventos de mensagem incluem o número conectado do workspace e o número do contato.from_phone e to_phone sempre representam o sentido real da mensagem. Para preservar esse contrato, mensagens sem uma conexão WhatsApp resolvida ou sem o número comercial da conexão não geram evento; o Flow registra a omissão em log para investigação.
message.sent, direction é outbound e from_phone é o business_phone. Mensagens de mídia podem incluir caption, media_url e mimetype. media_url só é emitida quando o provedor informa uma URL HTTP(S); URLs do provedor podem expirar e não devem ser tratadas como armazenamento durável.