Começando com Webhooks

O que são Webhooks?

Webhooks são chamadas HTTP POST que o Codewo dispara pro seu servidor sempre que algo relevante acontece — uma conversa é criada, um contato é atualizado, uma tag é adicionada. Em vez de você ficar consultando a API ("polling"), os eventos chegam até você.

Eventos disponíveis

Conversas:

• conversation.created
• conversation.assigned
• conversation.status_changed
• conversation.closed

Contatos:

• contact.created
• contact.updated
• contact.tag_added

Setup em 3 passos

1. Cadastre o endpoint em /settings/integrations/webhooks (URL HTTPS).
2. Salve o signing secret (whsec_*) — você precisa dele pra validar assinaturas.
3. Implemente o handler na sua aplicação.

Autenticação (HMAC-SHA256)

Cada request vem com o header X-Codewo-Signature: t=<unix>,v1=<hex_hmac>. Você valida:

1. Pegue o body cru (raw) do request
2. Calcule: hmac_sha256(secret, "{t}.{raw_body}")
3. Compare com o valor v1 do header (constant-time)
4. Verifique que t está dentro de uma janela aceitável (ex: 5 minutos)

Retry e auto-disable

Se seu endpoint falhar (não responder com 2xx em 10s), o Codewo retenta:

• 0s, 30s, 5min, 30min, 2h (5 tentativas)
• Após 5 falhas consecutivas, o endpoint é auto-desativado e o criador recebe notificação.

Documentação completa

Para shapes de payload, code samples (PHP, Node.js, Python) e detalhes técnicos, veja /desenvolvedores/webhooks.

Veja também

• Webhooks outbound: guia completo
• API Keys: criar e revogar