Defina o que o webhook precisa comunicar

Webhooks de pagamento notificam o portal sobre mudanças na origem. Em um cenário B2B, a aplicação confere a atualização para decidir o próximo estado do pedido.
Registre quais tipos de evento interessam e qual sistema confirma o estado final. O portal pode usar a notificação para iniciar uma atualização e conferir o pagamento com a origem.
Separe entrega, evento e operação de negócio
A entrega representa uma tentativa de enviar a mensagem. O evento identifica o fato comunicado. A operação de negócio indica o que a aplicação deve fazer com esse fato.
O provedor pode reenviar uma confirmação quando o portal demora a responder. Registre os identificadores que permitem relacionar as tentativas ao mesmo evento e ao pedido correspondente.
Documente três elementos antes de integrar:
- Tipos de evento relevantes para o pedido.
- Identificadores de entrega, evento e operação.
- Responsável por confirmar o estado final.
Confira as garantias do provedor
Use o guia de integração B2B para mapear responsáveis e dependências. No aceite, confira como a confirmação altera o estado exibido ao comprador.
Confira no contrato o prazo máximo de resposta aceito e a política de reenvio. Registre também como recuperar um evento quando a janela automática terminar sem confirmação do portal.
Verifique a origem e a integridade da entrega

Use o mecanismo de assinatura documentado pelo provedor. Confirme quais partes da mensagem entram na verificação e mantenha a representação original até concluir essa etapa.
Quando o protocolo assinar o horário, aplique a janela indicada pelo provedor. Trate a verificação temporal e a identificação de duplicatas como controles distintos.
Planeje a troca de credenciais
Separe as credenciais de teste e produção. Registre quem pode iniciar a troca e quais versões o serviço aceita durante a transição prevista pelo provedor.
Depois da troca, confirme que o recebimento legítimo continua funcionando. Revogue a credencial antiga conforme o prazo definido e confira o resultado em ambiente adequado.
Confira estes requisitos no recebimento:
- Assinatura verificada conforme o contrato do provedor.
- Credenciais específicas para cada ambiente.
- Registro do resultado sem gravar segredos.
Mantenha a validação de negócio no processamento
Uma assinatura válida confirma a origem e a integridade conforme o protocolo. A aplicação ainda precisa conferir se o pagamento corresponde ao pedido e à conta esperados.
Quando a mensagem não corresponder ao contrato, registre somente os detalhes necessários para investigar. Use a resposta prevista pelo provedor sem expor informações internas.
Teste uma mensagem alterada
Em ambiente autorizado, modifique um campo de uma mensagem assinada e confirme que a verificação recusa a entrega. Preserve o exemplo original para comparar os resultados.
Esse teste deve acompanhar mudanças no processamento do corpo da requisição. Uma transformação anterior à conferência pode invalidar a representação que o provedor efetivamente assinou.
Grave a entrega antes de confirmar o recebimento

Responder com sucesso indica que a aplicação assumiu responsabilidade pela entrega. Faça isso depois de guardar o evento em armazenamento durável ou concluir o processamento previsto.
Se a gravação falhar, use a resposta compatível com a política de novas tentativas. Assim, o provedor pode reenviar a mensagem conforme suas regras.
Defina o que a gravação precisa preservar
Guarde a referência do evento, o tipo e o horário de recebimento. Preserve os dados necessários ao processamento pelo período definido para o fluxo.
A equipe precisa distinguir gravação concluída de atualização de pedido concluída. Registre os dois marcos para que um alerta indique a etapa que ainda está pendente.
Defina quais marcos registrar por entrega:
- Identificação recebida e resultado da validação.
- Confirmação de armazenamento durável do evento.
- Resultado posterior do processamento de negócio.
Teste o intervalo entre gravar e responder
Em teste, interrompa a conexão depois da gravação e antes da resposta. Quando a origem reenviar a entrega, o serviço deve reconhecer o mesmo evento.
Inclua uma falha de armazenamento. A aplicação deve informar o resultado previsto pelo contrato e permitir que a operação acompanhe a recuperação sem perder a referência.
Verifique o armazenamento confirmado
Defina qual evidência permite afirmar que o evento está durável. O recebimento na memória do processo não demonstra que ele sobreviverá a uma interrupção do serviço.
Confira a recuperação depois de reiniciar o componente em teste. A referência armazenada deve permitir localizar o mesmo evento e continuar o processamento sem criar outra operação.
Separe o recebimento do processamento de negócio

O serviço que recebe o webhook pode validar e enfileirar a mensagem. Um processador independente executa as consultas e atualizações que exigem mais tempo.
Essa separação reduz a dependência do prazo de resposta do provedor. A fila absorve variações de demanda dentro da capacidade que a operação consegue monitorar.
Defina quando confirmar a mensagem na fila
O processador deve sinalizar conclusão depois de gravar o resultado necessário. Se perder a conexão nesse intervalo, uma nova execução deve consultar ou preservar o estado já confirmado.
Planeje a capacidade para picos previstos. Acompanhe o evento mais antigo na fila junto da quantidade de mensagens, pois cada medida revela um aspecto da recuperação.
Registre os estados que orientam a operação:
- Recebido e aguardando processamento.
- Processamento concluído com resultado registrado.
- Falha que exige nova tentativa ou análise.
Mantenha o estado do pedido rastreável
Associe o evento ao pedido somente depois de conferir as referências de negócio. Se não houver correspondência, encaminhe o caso a uma fila de análise.
Use identificadores estáveis para relacionar a entrega, o processamento e a decisão final. O atendimento consegue localizar a pendência sem pedir que o comprador repita o pagamento.
Mantenha a referência ao longo da fila
Preserve a identidade do evento nas mensagens e nos registros de processamento. O suporte precisa seguir o percurso sem depender do conteúdo comercial completo para localizar cada etapa.
Se a fila utilizar um corpo reduzido, confira onde recuperar os dados necessários. Essa dependência também precisa permanecer disponível durante o período previsto para reprocessamento.
Identifique duplicatas de entrega e de negócio

A origem pode enviar novamente o mesmo evento depois de uma interrupção. Registre o identificador emitido pelo provedor para reconhecer a repetição no contexto da conta e do ambiente.
Eventos diferentes também podem descrever o mesmo resultado comercial. Nessa situação, consulte a referência do pagamento e a transição do pedido que a mensagem pretende registrar.
Proteja o registro contra processamento simultâneo
Dois processadores podem receber a mesma entrega antes de qualquer um concluir. Use uma restrição de unicidade ou uma operação atômica para impedir que ambos a tratem como inédita.
Se a atualização já ocorreu, preserve o resultado e registre a repetição. Para uma operação externa, mantenha a mesma referência em novas tentativas quando o destino aceitar esse contrato.
Distinga os casos no histórico da integração:
- Mesmo evento recebido em tentativas diferentes.
- Eventos distintos sobre a mesma transição.
- Nova atualização legítima para o mesmo pedido.
Defina por quanto tempo reconhecer repetições
Considere a janela de reenvio e o período em que a operação pode recuperar entregas manualmente. A retenção do identificador pode seguir uma regra diferente da retenção do corpo completo.
Valide o comportamento com dois recebimentos simultâneos. O pedido deve manter uma única confirmação, e a equipe deve conseguir explicar por que as duas entregas receberam respostas válidas.
Trate eventos que chegam fora de ordem

Um aviso de pagamento aprovado pode chegar antes de outro que descreve a análise inicial. A ordem de chegada, sozinha, pode levar o portal a mostrar um estado anterior.
Use a versão do recurso quando o provedor oferecer uma sequência confiável. Quando essa informação não estiver disponível, confira a transição permitida ou consulte o estado atual na origem.
Registre as transições permitidas
Um pagamento confirmado pode seguir para estorno quando houver uma atualização válida. Uma mensagem atrasada de análise, por outro lado, deve preservar a confirmação já registrada.
Descreva os estados e o responsável por confirmar cada mudança. Se o pagamento ficar incerto, mostre uma pendência rastreável até obter evidência suficiente.
Confira três elementos ao mudar o estado:
- Estado atual e referência associada ao pedido.
- Versão ou condição informada pela origem.
- Transição admitida pelo fluxo de pagamento.
Teste a chegada em sequências distintas
Prepare três mensagens do mesmo pagamento e execute o fluxo em ordem normal e invertida. Compare o estado final e a quantidade de decisões registradas em cada caso.
Inclua duas atualizações concorrentes se a operação receber entregas em paralelo. A aplicação precisa preservar o resultado confirmado e identificar quais mensagens ainda merecem conferência.
Diferencie revisão e sequência
Um horário registrado pelo consumidor não substitui uma versão confiável do recurso. Use somente a ordenação que o contrato permite interpretar para decidir sobre uma transição.
Quando a origem não oferecer essa garantia, preserve a incerteza e consulte o estado correspondente. O portal deve explicar por que manteve ou alterou a situação do pedido.
Limite novas tentativas e encaminhe falhas persistentes

Uma indisponibilidade temporária do ERP pode justificar nova tentativa. Já uma referência desconhecida pode exigir investigação antes que a equipe decida se deve reprocessar o evento.
Classifique falhas pelo que precisa mudar para o processamento avançar. Uma resposta temporária pode desaparecer com a recuperação do serviço, enquanto um contrato incompatível exige correção.
Separe o reenvio do provedor da tentativa interna
O provedor controla novas entregas conforme seu contrato. Depois que a aplicação confirma o recebimento, ela precisa acompanhar as próprias tentativas de processamento.
Defina intervalos crescentes e um limite coerente com o prazo da operação. Evite retentar continuamente quando o serviço de destino já estiver acumulando pendências.
Registre como recuperar falhas de processamento:
- Tipo de erro e tentativa mais recente.
- Próximo processamento previsto dentro do limite.
- Responsável quando a falha persistir.
Preserve o contexto para investigação e recuperação
Encaminhe falhas persistentes a uma fila ou registro de análise com referência ao evento original. Dê ao responsável os dados necessários para entender em que etapa ocorreu o erro.
Após corrigir a causa, reexecute com a mesma referência de negócio. Confira o estado do pagamento antes de repetir ações que possam gerar confirmação, notificação ou efeito financeiro.
Defina quem autoriza uma recuperação manual
Uma falha persistente precisa de um encaminhamento que preserve a referência original. Registre quem pode aprovar a retomada e qual verificação deve preceder efeitos comerciais.
Depois da execução, compare o estado confirmado com o resultado esperado. Encerrar o chamado exige evidência da recuperação, além do registro de que alguém acionou o reprocessamento.
Reconcilie o histórico do provedor com o pedido

Um webhook pode ficar pendente ou ultrapassar a janela de novas tentativas. A reconciliação procura mudanças que a origem confirmou e que ainda não aparecem no portal.
Compare períodos equivalentes e use referências estáveis. No exemplo, associe o identificador do pagamento ao pedido e verifique o estado nos dois sistemas.
Defina como lidar com diferenças
Se a origem confirmar o pagamento e o pedido continuar pendente, confira o registro de recebimento. A mensagem pode estar ausente, aguardando processamento ou encaminhada para análise.
O tratamento depende dessa etapa. Recupere um recebimento ausente pela via oferecida pelo provedor e revise o processamento interno quando a entrega já estiver registrada.
Classifique as divergências antes de agir:
- Pagamento confirmado sem evento no histórico local.
- Evento recebido com processamento ainda pendente.
- Processamento registrado sem atualização do pedido.
Verifique se a recuperação encerra a pendência
Após recuperar um evento, compare novamente o estado do pedido e a referência do pagamento. Registre qual ação resolveu a divergência e quem confirmou o resultado.
Defina a periodicidade da conciliação segundo o impacto do atraso. Uma compra que depende da confirmação para seguir à expedição pode exigir uma janela menor.
Preserve o recorte da conciliação
Guarde o período, o fuso e as condições usadas na comparação entre origem e portal. Uma diferença de janela pode parecer evento ausente sem representar perda real.
Registre quais casos ficaram fora da cobertura disponível e como serão tratados. A equipe precisa distinguir divergência confirmada de pendência que ainda depende de consulta adicional.
Acompanhe a idade da fila e as falhas

Um serviço pode responder rapidamente e ainda acumular pedidos pendentes. Monitore o tempo de recebimento e o tempo até o resultado de negócio como medidas distintas.
Combine o volume na fila com a idade do evento mais antigo. Um pico breve pode gerar muitas mensagens, enquanto um único evento parado também pode exigir investigação.
Dê contexto a cada alerta
Mostre a etapa, o tipo de evento e a referência útil para localizar a falha. Restrinja detalhes comerciais aos sistemas usados pelas equipes autorizadas.
Defina responsáveis por atrasos de recebimento, processamento e dependências externas. O primeiro atendimento deve conseguir identificar a equipe que pode resolver o caso.
Acompanhe três indicadores durante a operação:
- Idade do evento pendente mais antigo.
- Falhas persistentes por tipo de operação.
- Divergências em aberto na reconciliação.
| Indicador | Evidência | Resposta inicial |
|---|---|---|
| Idade da fila | Evento mais antigo | Conferir capacidade |
| Falha persistente | Última tentativa | Identificar a causa |
| Divergência | Estado na origem | Reconciliar referências |
Revise quando os limites deixarem de representar o fluxo
Compare os limites com o prazo real de confirmação dos pedidos. Uma mudança de volume ou na disponibilidade do ERP pode exigir uma revisão.
Mantenha o histórico dos alertas e das ações tomadas. Use esse histórico para ajustar a operação quando o mesmo tipo de atraso se repetir.
Teste interrupções e recuperação antes da liberação

Prepare um roteiro em ambiente de teste com dados fictícios e uma origem autorizada. Escreva o estado esperado do evento, da fila e do pedido antes de executar cada cenário.
Comece com um recebimento válido e confirme as referências no histórico. Depois, avalie atrasos e interrupções que o contrato e a operação precisam absorver.
Inclua falhas em pontos distintos
Interrompa o armazenamento para observar a resposta ao provedor. Em outro cenário, mantenha o armazenamento disponível e simule indisponibilidade no sistema de negócio.
Confira também uma confirmação que chega fora de ordem. O portal deve preservar o estado coerente e registrar como avaliou a atualização.
Inclua três condições no cenário de aceite:
- Resposta perdida após gravação do evento.
- Fila com processamento temporariamente interrompido.
- Estado recuperado após falha da integração.
Documente o resultado operacional
Registre que o portal concluiu o pedido uma vez e que a equipe localizou as entregas relacionadas. A evidência precisa incluir o estado final e a referência original.
Use os critérios de testes por risco para distribuir as verificações. Reserve um cenário completo para demonstrar que a recuperação chega ao estado que o comprador consegue consultar.
Valide a passagem para o suporte
Peça a outra pessoa que investigue uma pendência fictícia usando as instruções e os acessos previstos. Observe se ela encontra evento, pedido e próximo passo sem ajuda informal.
Guarde as lacunas identificadas no roteiro de operação. O aceite precisa demonstrar tanto a recuperação técnica quanto a capacidade de acompanhar casos que ainda exigem intervenção.
Conclusão

Verifique a origem, grave o evento antes de confirmar o recebimento e separe a entrega da atualização do pedido. Cada etapa precisa deixar uma referência verificável.
Planeje o comportamento quando a origem reenviar, o destino falhar ou os eventos chegarem fora de ordem. Use fila, reconciliação e acompanhamento para localizar e resolver pendências.
Confira estes resultados antes de liberar:
- Recebimento confiável com confirmação após gravação.
- Pedido consistente após novas tentativas.
- Recuperação rastreável quando houver divergência.
Preserve a decisão comercial
Relacione a entrega ao evento e à transição que o pedido pode receber. A aplicação precisa reconhecer repetições sem bloquear atualizações legítimas, como uma revisão posterior de pagamento.
Quando o resultado continuar incerto, mantenha uma pendência rastreável. A consulta à origem e a conciliação devem orientar a resolução antes de repetir um efeito financeiro.
Mantenha evidências de recuperação
Guarde o roteiro de testes, as referências fictícias e os resultados esperados. Outra pessoa precisa conseguir reproduzir o cenário e reconhecer qual etapa permaneceu pendente.
Inclua a resposta perdida depois da gravação e a falha posterior de processamento. Esses cenários permitem verificar responsabilidades diferentes sem confundir recebimento com conclusão do pedido.
Entregue continuidade à operação
Defina responsáveis por credenciais, filas, alertas e conciliação. Cada atividade precisa de instruções que permitam localizar o caso e escolher o encaminhamento compatível com o contrato.
Revise essas instruções quando mudarem volumes, prazos ou comportamentos do provedor. Preserve as evidências anteriores para explicar por que a operação adotou seus limites e procedimentos atuais.
Perguntas frequentes
Estas respostas resumem as decisões de recebimento, processamento e recuperação de webhooks.
Quando confirmar o recebimento?
Depois que a aplicação assumir responsabilidade pelo evento por meio de gravação durável ou processamento concluído.
Por que um webhook chega duas vezes?
O provedor pode reenviar quando não recebe a confirmação prevista ou quando a operação solicita uma nova entrega.
Como reconhecer a mesma entrega?
Use os identificadores do provedor e considere o contexto da conta e do ambiente.
Como preservar a confirmação do pedido?
Associe a atualização ao pagamento correto e aplique apenas transições permitidas pelo fluxo.
Como lidar com mensagens atrasadas?
Confira a versão ou o estado atual na origem e preserve a transição comercial válida.
Quando retentar o processamento?
Retente falhas transitórias dentro do limite acordado e encaminhe falhas persistentes à operação.
O que colocar na fila?
Guarde o evento verificado ou uma referência recuperável junto dos dados necessários ao processamento.
Qual métrica mostra atraso?
A idade do evento pendente mais antigo revela há quanto tempo um item espera processamento.
Como recuperar um evento ausente?
Consulte o histórico da origem e use a via autorizada de recuperação com a mesma referência de negócio.
O que testar antes de liberar?
Confira recebimento, repetição, ordem de eventos, falha temporária e recuperação com resultados verificáveis.











Deixe um comentário