Webhooks outbound: guia completo

Detalhes técnicos completos de webhooks outbound do Codewo: 7 eventos disponíveis, autenticação HMAC-SHA256, retry com backoff exponencial, auto-disable após 5 falhas consecutivas, e rotação graceful do signing secret. Pra introdução, ver Começando com Webhooks.

Os 7 eventos

Evento	Quando dispara
conversation.created	Conversa nova criada
conversation.assigned	Conversa atribuída a alguém (membro/equipe)
conversation.status_changed	Status mudou (Open → In Progress, etc.)
conversation.closed	Conversa fechada (Resolved, Closed, Spam)
contact.created	Contato novo criado
contact.updated	Campo do contato modificado
contact.tag_added	Tag adicionada a contato

Você pode subscrever a um ou mais eventos por endpoint.

Setup

Em Configurações → Integrações → Webhooks:

1. Novo endpoint.
2. URL — Sua URL HTTPS pra receber POST.
3. Eventos — Marque quais quer receber.
4. Salvar. O sistema cria um signing secret no formato whsec_* e mostra uma única vez. Copie.

Payload e headers

Para cada evento, o Codewo manda:

POST https://sua-url.com/codewo-webhook HTTP/1.1
Host: sua-url.com
Content-Type: application/json
X-Codewo-Event: conversation.created
X-Codewo-Delivery: 01HQXY... (ULID único)
X-Codewo-Signature: t=1715712345,v1=abcdef0123...
User-Agent: Codewo-Webhook/1.0

{
  "event": "conversation.created",
  "timestamp": "2026-05-14T10:25:45Z",
  "data": {
    "conversation": { ... },
    "contact": { ... },
    "channel": { ... }
  }
}

• X-Codewo-Event — Nome do evento.
• X-Codewo-Delivery — ULID único do envio. Use como idempotency key — se receber a mesma delivery 2x (raro mas pode acontecer no retry), processe só uma.
• X-Codewo-Signature — Assinatura HMAC-SHA256.

Validação da assinatura

1. Pegue o raw body do request (não parsed).
2. Pegue do header X-Codewo-Signature os valores t (timestamp) e v1 (hex hmac).
3. Calcule esperado: hmac_sha256(secret, "{t}.{raw_body}")
4. Compare expected com v1 (comparação constant-time pra evitar timing attack).
5. Valide que t está dentro de janela aceitável (ex: 5 minutos).

Crítico: use o body cru, não parsed/normalizado. Espaço em branco a mais ou serialização diferente quebra HMAC.

Resposta esperada

• 2xx (200, 201, 204) — Codewo considera entregue, marca delivery como sucesso.
• Não-2xx ou timeout (10s) — Falha. Codewo agenda retry.

Retry com backoff

Se entregar falhar (não-2xx, timeout, network error), o Codewo retenta:

• Tentativa 1: Imediato (no envio original).
• Tentativa 2: 30 segundos depois.
• Tentativa 3: 5 minutos depois.
• Tentativa 4: 30 minutos depois.
• Tentativa 5: 2 horas depois.

Total: 5 tentativas. Se todas falharem, o evento é descartado.

Auto-disable

Após 5 falhas CONSECUTIVAS em entregas diferentes (não a mesma delivery 5x — eventos diferentes seguidos falhando), o endpoint é automaticamente desativado.

• Status do endpoint vira "Auto-disabled".
• Não recebe mais nenhum evento.
• Criador do endpoint recebe notificação in-app webhook_auto_disabled + email.

Pra reativar: corrija o problema da sua aplicação e clique em "Reativar" na lista de endpoints.

Rotação graceful do secret

Secret pode ser comprometido (vazamento, ex-funcionário, etc.). Pra rotacionar sem downtime:

1. Em Webhooks → [endpoint] → Rotacionar secret.
2. Sistema gera secret novo e mantém o anterior por 24 horas.
3. Durante essa janela, sua aplicação deve aceitar assinaturas com qualquer um dos dois.
4. Após 24h, o antigo é descartado automaticamente.

Tem 24h pra atualizar suas envs / código. Não precisa parar produção.

Audit log

Toda entrega fica registrada em tabela append-only webhook_deliveries:

• ULID (= X-Codewo-Delivery).
• Timestamp de envio.
• Status HTTP recebido.
• Tempo de resposta.
• Tentativa (1–5).

Retenção: 30 dias. Depois disso, deliveries antigas são purgadas (você ainda vê estatísticas agregadas).

Pegadinhas comuns

• Auto-disable acontece silencioso pro time inteiro. Só o criador é notificado. Se você criou e saiu de férias, ninguém vê — e fluxos param.
• Idempotência é sua responsabilidade. Use X-Codewo-Delivery como chave. Receber 2x não deve criar 2 recursos no seu lado.
• Body de validação HMAC tem que ser raw. Frameworks que fazem auto-parse JSON podem trocar a serialização. Em Node.js Express, configure express.raw() na rota do webhook.
• Replay attacks. Se um atacante intercepta um webhook válido, ele pode tentar replay. Mitigue verificando timestamp (rejeitar > 5min) e armazenando deliveries vistas pra rejeitar duplicatas além da janela.
• Conexão lenta = retry. Se sua URL demora 11s pra responder, contamos como timeout. Faça processamento assíncrono — receba o webhook, jogue numa fila interna, retorne 200 imediatamente.
• Webhook em ambiente local não funciona em produção. Codewo Cloud não consegue mandar pra localhost. Use ngrok ou similar pra desenvolvimento.
• Secret é encriptado em repouso, mas não hashed. HMAC precisa do plaintext pra assinar. Não tente "comparar hash" — não é assim.

Boas práticas

• Endpoint dedicado. Tenha URL específica (/integrations/codewo-webhook) — não misture com endpoints normais.
• Processamento assíncrono. Receba, valide, enfileire, retorne 200. Processamento real fica numa fila/queue.
• Verifique HMAC SEMPRE. Sem verificação, qualquer um pode falsificar webhook.
• Audit log no seu lado. Salve cada webhook recebido (delivery ID + status do seu processamento) pra debug.
• Monitor de saúde. Alerta se taxa de erro do seu endpoint passar de X% — auto-disable pega depois, alerta seu pega antes.
• Documente a integração. Em 1 ano, ninguém lembra qual webhook trigger qual ação no seu sistema.

Veja também

• Começando com Webhooks
• API Keys: criar e revogar
• Integrações externas