Webhooks
Detalhes
Boas práticas para integração estável: evitar processar duas vezes, entender reentregas e acompanhar status.
Falhas e boas práticas
Três pontos evitam a maior parte dos problemas em produção:
Responda com 2xx quando der certo
Status HTTP 2xx significa que você aceitou a entrega; a Alocis não agenda novas tentativas para esse fato após um 2xx. Só responda 2xx depois de validar o token e estar pronto para processar (ou enfileirar) o evento.
Valide o token
Cada POST traz o token da conta no campo token (prefixo whtok_). Compare com o valor copiado do painel antes de liberar acesso ou disparar automações. Se estiver ausente ou diferente, responda com erro (por exemplo 401) e não execute ações sensíveis.
Evite processar duas vezes
Cada entrega tem um id único (whdlv_ no JSON ou cabeçalho X-Webhook-Id). Reentregas automáticas repetem o mesmo id e o mesmo corpo gravado na primeira tentativa — use esse id como chave para não duplicar efeitos no seu sistema.
Erros temporários (timeout, 408, 429, 5xx) são reentregues dentro de uma janela de 24 horas a partir da primeira tentativa, com até 8 tentativas e intervalos de 1 min, 5 min, 15 min, 1 h, 4 h e 12 h. Demais respostas 4xx são tratadas como falha definitiva. Veja a tabela abaixo.
Idempotência
Idempotência significa: se a mesma entrega chegar de novo, seu sistema não deve repetir o efeito (duplicar acesso, duplicar pedido, etc.).
- Use o id da entrega (campo id no JSON ou cabeçalho X-Webhook-Id, prefixo whdlv_) como chave — guarde os ids já processados.
- Reentregas automáticas reutilizam o mesmo id e o mesmo conteúdo de negócio gravado na primeira tentativa.
Reentregas e falhas
Falhas temporárias são reenviadas dentro de uma janela de 24 horas a partir da primeira tentativa, com até 8 tentativas e intervalos de 1 min, 5 min, 15 min, 1 h, 4 h e 12 h (a última usa o tempo restante da janela).
| HTTP | Significado |
|---|---|
2xx | Entrega aceita; não há novas tentativas para este fato. |
408, 429, 5xx | Erro temporário — nova tentativa agendada dentro da janela. |
4xx (demais) | Erro definitivo — a entrega é marcada como falha sem novas tentativas. |
| Timeout ou conexão | Tratado como erro temporário (mesma política de 5xx). |
Endpoints pausados ou removidos não recebem eventos novos; entregas em andamento seguem a política de retry até aceitar ou esgotar a janela.
Status no painel
Em Complementos → Webhook → Entregas você vê se cada POST foi aceito, falhou ou está em retry, quantas tentativas ocorreram e um corpo redigido para diagnóstico. Destinos pausados não recebem eventos novos.
Em novas tentativas, a Alocis reenvia o mesmo snapshot gravado na primeira tentativa — o payload descreve o estado no momento do fato, não o estado atual do recurso.