Eventos
no seu servidor.
Codewo dispara POST HTTPS assinado pra URL que você cadastra sempre que algo relevante acontece. HMAC-SHA256 padrão Stripe, retry exponencial, auto-disable. Pare de fazer polling.
X-Codewo-Signature: t=<unix>,v1=<hex_hmac> HMAC-SHA256 sobre "{t}.{raw_body}" com seu signing secret.
5 tentativas
backoff 0s → 2h
Auto-disable após 5 falhas seguidas.
Visão geral
Você cadastra um endpoint HTTPS + escolhe os eventos. Quando algo acontece (conversa criada, contato atualizado, etc.), o Codewo enfileira um job que faz POST JSON assinado pro seu endpoint em segundos. Resposta 2xx encerra o ciclo. Qualquer outra coisa entra em retry exponencial.
Cadastre
URL https:// + lista de eventos. Signing secret é exibido uma vez.
Codewo dispara
POST JSON com timeout de 10s. Headers identificam evento + delivery ID.
Você responde 2xx
Outras respostas viram retry com backoff exponencial. Após 5 falhas seguidas, endpoint é pausado.
Autenticação
Cada endpoint tem seu próprio signing secret com prefixo whsec_*, mostrado UMA vez na criação. Toda request leva o header X-Codewo-Signature com a assinatura HMAC-SHA256 do body — sem assinar = sem origem comprovada.
Cifrado em repouso
HMAC precisa do plaintext pra assinar, então o secret vai pro banco cifrado com APP_KEY (não hashed como API key).
Constant-time compare
Use hash_equals / timingSafeEqual / compare_digest — `===` vaza timing.
Rotação graceful
Ao rotacionar, o secret antigo continua válido por 24h — você atualiza a env do seu servidor sem perder entregas.
Replay protection
Validar HMAC NÃO basta — rejeite também requests com t mais antigo que 5min.
Catálogo de eventos
Cada endpoint subscreve um subconjunto. Envelope é igual pra todos: { id, type, created_at, data }. Clique pra ver o shape exato de data.
Conversas
Contatos
Headers enviados
Em destaque os três que importam pra implementação: X-Codewo-Event pra rotear, X-Codewo-Delivery pra deduplicar, X-Codewo-Signature pra autenticar.
| Header | Exemplo | Uso |
|---|---|---|
Content-Type | application/json | Fixo. |
User-Agent | Codewo-Webhooks/1.0 | Identifica o originador no seu log. |
X-Codewo-Event | conversation.created | Tipo do evento. Use pra rotear handler. |
X-Codewo-Delivery | 01HX5Z4QYJ7K... | ULID único por tentativa. Use como chave de idempotência. |
X-Codewo-Signature | t=<unix>,v1=<hex> | Assinatura HMAC-SHA256 sobre "t.body". Sempre valide antes de processar. |
Verificação HMAC
Sempre valide a assinatura ANTES de processar o evento. Snippets cobrem replay-protection (5min) e idempotency.
// $secret = 'whsec_...' (variável de ambiente)
$header = $request->header('X-Codewo-Signature');
[$tPart, $sigPart] = explode(',', $header);
$timestamp = explode('=', $tPart)[1];
$signature = explode('=', $sigPart)[1];
// Replay protection (5min)
if (abs(time() - (int) $timestamp) > 300) {
abort(403);
}
$expected = hash_hmac(
'sha256',
"{$timestamp}." . $request->getContent(),
$secret
);
if (! hash_equals($expected, $signature)) {
abort(403);
}
// Idempotência por delivery ID
$deliveryId = $request->header('X-Codewo-Delivery');
// ... pule se já processou este delivery_idRetry & auto-disable
Qualquer resposta fora de 2xx (timeout, conexão recusada, 4xx, 5xx) entra em retry com backoff exponencial. Após 5 falhas consecutivas o endpoint é pausado automaticamente e o criador recebe notificação in-app. Reative manualmente em /settings/integrations/webhooks.
| Tentativa | Atraso após falha anterior |
|---|---|
| 1 | Imediato |
| 2 | 30 segundos |
| 3 | 5 minutos |
| 4 | 30 minutos |
| 5 | 2 horas |
Idempotência
Retries fazem o mesmo evento lógico chegar mais de uma vez. Sua aplicação precisa ser idempotente. Use o header X-Codewo-Delivery (ULID único por tentativa) ou o campo id do payload como dedupe key. TTL de 7 dias na sua cache de IDs processados é mais que suficiente — depois disso o retry-loop já terminou.
Rotação do signing secret
Recomendamos rotacionar periodicamente. Quando você roda "Rotacionar secret" no painel, um novo é gerado e o antigo continua válido por 24h. Janela em que você atualiza o secret no seu servidor sem perder entregas. Após o TTL, apenas o novo é aceito.
Leia o secret de variável de ambiente. Em produção, use ferramenta de rotação automatizada (AWS Secrets Manager, Vault, Doppler) e dispare deploys quando o valor mudar.
Nunca exponha o secret em frontend
Webhook signing secret só vive no seu backend. Se for parar em log, console, repositório ou bug-tracker, rotacione imediatamente.