Webhooks confiáveis: retentativas, assinaturas e ordem

Entregar eventos com backoff, verificação HMAC e idempotência no receptor.

Contexto

Este artigo integra a série Integração & APIs no blog da Barre — pensado para CTOs, arquitetos e líderes de produto que precisam de decisões com critério e continuidade operacional, não de modismos.

Pressão de negócio e restrições

Integrações são produtos distribuídos: mudança num lado é mudança para o outro — sem versão e comunicação, cada deploy é negociação sob stress.

Relacionado com o foco anunciado no título: Entregar eventos com backoff, verificação HMAC e idempotência no receptor.

Padrões que voltam a aparecer

• Integrações críticas sem medição acordada entre produtor e consumidor.

• Correlação ausente nos registos — diagnóstico vira caça ao tesouro.

• Contratos implícitos — alterações partem integrações sem aviso.

Decisão em uma frase, aplicada

Decisão útil: partilhar definição de disponível entre produtor e consumidor — uma métrica, um dono.

Quanto mais curto e verificável o compromisso, maior a probabilidade de sobreviver a mudanças de equipa.

Consequências, trade-offs e o que vigilar

Compatibilidade custosa é preço de integrações sem versão e sem testes de contrato — muitas vezes pago pelos consumidores, não por quem altera.

Trade-offs: sincronia simples vs assincronia resiliente — este texto empurra para contrato explícito e política de falha antes do primeiro «apagão».

O que vigilar

• Taxa de erro e latência por integração crítica.

• Retries e duplicações em operações sensíveis.

• Compatibilidade anunciada vs uso real pelos clientes internos/externos.

Próximos passos (se for prioridade agora)

1. Publicar contrato versionado e política de deprecação.

2. Acordar SLIs e runbook partilhado nas integrações críticas.

3. Ensaiar falhas (timeout, 429, payload inválido) em sandbox.

Síntese

Webhooks confiáveis resume-se a isto: menos ambiguidade, mais decisão repetível — o resto são ferramentas ao serviço desse critério.

---

Resumo: Entregar eventos com backoff, verificação HMAC e idempotência no receptor.