Recursos · 54
Webhooks: lidar com repetições, atrasos e recuperação
Transformar uma notificação recebida em um efeito comercial único e rastreável, recuperável após uma falha.
Atualizado · 3 min
O que este guia ajuda a alcançar
- Autenticar notificações
- Separar o recibo do processamento
- Impedir efeitos duplicados
- Recuperar eventos bloqueados
Verificação rápida
- Quais bytes são assinados?
- Quando o recibo é durável?
- Dois workers podem agir em conjunto?
- O provedor garante a ordem?
- Como um evento perdido é encontrado?
Método passo a passo
- 1
Ler o contrato do provedor
Tipos de registro, versão, contexto da conta, assinaturas, tempo e regras de repetição. O Stripe afirma que a ordem de entrega não é garantida e que duplicatas podem ocorrer; não aplique um atraso específico do Stripe a cada API.
Entregável: contrato do provedor com data.
- 2
Validar antes dos efeitos
Verificar assinaturas com a biblioteca e o corpo bruto exigidos pelo provedor. Limitar tamanhos e tipos aceitos. Testar assinaturas inválidas e contexto de conta inesperado em um ambiente autorizado sem registrar segredos.
Entregável: negações sem efeitos.
- 3
Persistir antes de confirmar
Separar o recebimento durável do processamento lento. Se a fila não puder aceitar o evento, não o reporte como retido. Sucesso indica recebimento sob seu contrato, não necessariamente a conclusão da ação comercial.
Entregável: estados recebido, em processamento, concluído e bloqueado.
- 4
Impor idempotência
Definir chaves de evento e identidade de efeito comercial. Testar repetições simultâneas em vez de apenas entrega sequencial. Uma verificação preliminar sem restrições atômicas ou bloqueio pode permitir que dois workers criem o mesmo efeito.
Entregável: evidência de unicidade do efeito.
- 5
Lidar com atrasos e desordem
Não assuma que uma notificação antiga descreve o estado atual. Consulte a fonte quando o contrato permitir e aplique transições de negócios validadas. Mantenha os eventos que ainda não podem ser interpretados.
Entregável: transições e testes de ordem inversa.
- 6
Conciliar e reproduzir
Prepare uma fila de erros com proprietário, causa, tentativas e fechamento. Mantenha a proteção contra duplicatas durante a reprodução. Compare periodicamente o provedor e o aplicativo: uma recuperação bem-sucedida não prova que nenhum evento foi perdido.
Entregável: procedimento de recuperação e relatório de discrepâncias.
Planilha reutilizável
Preencha com suas observações autorizadas. Estes campos são um modelo de trabalho, não resultados observados.
| Campo | Informações a serem registradas |
|---|---|
| Evento | Provedor, conta, identificador e versão |
| Recibo | Assinatura validada e carimbo de data/hora permanente |
| Efeito | Chave de negócio, estado e evidência de unicidade |
| Recuperação | Causa, tentativa, proprietário e encerramento |
Exemplo prático fictício
Situação ilustrativa
Exemplo fictício: dois trabalhadores recebem a mesma notificação de confirmação durante a recuperação.
Decisão e evidências esperadas
Uma restrição de efeito comercial única e um estado transacional permitem um cumprimento único, enquanto ambas as entregas permanecem rastreáveis.
Distinguir os mecanismos
| Mecanismo | Finalidade | Verificação ou limitação |
|---|---|---|
| Assinatura | Valide a origem de acordo com o contrato | Não torna os efeitos únicos |
| Desduplicação | Reconhecer notificações repetidas | Verificar também a concorrência e os efeitos comerciais |
| Conciliação | Encontrar omissões e diferenças | Nomear a origem e o período |
Indicadores de gestão
| Indicador | O que mede | Primeira ação |
|---|---|---|
| Idade da fila | Atraso de eventos incompletos | Inspecionar o mais antigo |
| Efeitos duplicados | Ações comerciais repetidas por engano | Corrigir a atomicidade |
| Lacunas entre origem e aplicação | Estados ausentes ou divergentes | Conciliar com evidências de fechamento |
Erros comuns
- Analisar antes da verificação do corpo assinado
- Confirmar antes do recebimento duradouro
- Assumir entrega ordenada
- Testar duplicados apenas sequencialmente
Perguntas frequentes
O sucesso HTTP significa que o processamento está completo?
Depende do contrato. Com processamento assíncrono, deve significar recebimento duradouro, enquanto o estado comercial é rastreado separadamente.
É possível assumir a entrega exatamente uma vez?
Projeto para repetições e falhas sob o contrato real, com efeitos únicos e reconciliação.
O corpo inteiro deve ser retido?
Somente quando necessário, com acesso e retenção adequados. Rastreamentos mínimos devem suportar o diagnóstico e a recuperação sem manter segredos.
Referências oficiais
As referências apoiam o método. Adapte as verificações ao seu contexto; elas não são uma certificação. Os títulos das referências originais e os documentos de origem podem estar em outro idioma.
Referências consultadas em .
