Como obter resultados confiáveis com a Toden
Charles Archibong, Cofundador
Receba resultados do Toden de forma confiável com um receptor webhook assinado. Verifique os bytes exatos, armazene cada evento de forma durável e recupere tentativas sem repetir a ação do cliente.
Pontos principais
- Assinaturas adulteradas ou expiradas serão rejeitadas.
- Um reenvio lógico desencadeia uma ação comercial.
- A recuperação do receptor persiste mesmo após a reinicialização do processo.
- Eventos atrasados não podem sobrescrever o estado mais recente.
- O regime de rotação funciona durante todo o período de tolerância.
Receber Toden Obtenha resultados confiáveis com um receptor webhook assinado. Verifique os bytes exatos, armazene cada evento de forma durável e recupere tentativas sem repetir a ação do cliente.
Antes de começar
Um ponto de extremidade do servidor que verifica assinaturas
Manipulação durável de duplicatas e recuperação de novas tentativas
Um autorizado API chave para recuperação de resultados do servidor
Use um membro da equipe com permissão para este controle. Verifique a organização e o ambiente antes de alterar qualquer configuração. Revise o preço atual antes de efetuar um pagamento ou renovar a assinatura. As capturas de tela mostram um exemplo de espaço de trabalho ou a referência de integração pública; elas não mostram um cliente real nem um pagamento efetuado.
Configure e utilize a funcionalidade.
Etapa 1: Preparar o receptor de back-end
Criar um público HTTPS endpoint com certificado válido e sem redirecionamento. Ele deve receber o corpo da requisição bruta exato antes de JSON O middleware resolve isso. Planeje uma caixa de entrada robusta, indexada por IDs de eventos lógicos, e processamento em segundo plano para tarefas lentas. O receptor deve estar no seu backend; um callback do navegador não substitui a entrega confiável de resultados.
Referência de integração: Algoritmo de verificação
Etapa 2: Crie o endpoint do webhook do ambiente
No ambiente Sandbox, abra Desenvolvedores → Webhooks → Adicionar endpoint . Insira o endpoint. URL Escolha a versão de corpo compatível e selecione as famílias de eventos que sua integração manipula. Selecione " Criar endpoint" e salve o segredo de assinatura do endpoint exibido no seu armazenamento de segredos de backend. Mantenha-o separado do seu API Importante: Os ambientes de Sandbox e Produção precisam de endpoints e segredos adequados ao ambiente.
Referência de integração: Sequência de testes recomendada
Etapa 3: Verifique a assinatura V2 antes da análise.
Ler X-Myaza-Signature-V2 , analisar o carimbo de data/hora assinado e os candidatos v1, rejeitar carimbos de data/hora inválidos ou expirados e verificar HMAC - SHA256 sobre o carimbo de data/hora, um ponto final e os bytes brutos exatos. Use o segredo do ponto de extremidade e a comparação de tempo constante. Durante a rotação, aceite uma assinatura válida do segredo de tolerância ativo ou não expirado. Use o documentado SDK ou um exemplo de receptor em vez de um formato de assinatura inventado.
Referência de integração: Cabeçalhos assinados
Etapa 4: Persistir no evento lógico antes do reconhecimento
Após a verificação da assinatura, analise o JSON e armazene o ID do envelope sob uma restrição de unicidade durável. Elimine tarefas duplicadas usando esse ID, não o ID da entrega. Um reenvio ou um alias de compatibilidade pode transportar o mesmo evento lógico em outra entrega. Retorne um código 2xx somente após a aceitação durável; coloque tarefas lentas em fila separadamente. Um código 2xx rápido sem um registro durável pode perder o resultado após uma falha.
Referência de integração: Asserção de idempotência
Etapa 5: Conciliar o resultado atual do produto
Use a referência documentada de cliente, verificação, transação ou atividade para a família de eventos. Mantenha os campos `status` e `checkStatus` distintos para verificações. Os eventos podem chegar fora de ordem, portanto, recupere o estado atual do recurso ou use a versão compatível antes de uma alteração sensível. Campos opcionais desconhecidos e tipos de evento não devem causar falhas no seu receptor. Uma notificação por si só não autoriza a liberação de fundos.
Referência de integração: Asserção de ordenação
Etapa 6: Teste de entrega, reprodução e rotação
Abra a ação de teste do endpoint e envie um evento simulado compatível. Inspecione o histórico de entrega e o registro permanente do destinatário. Reenvie o evento e comprove que a ação comercial ocorre uma única vez. Teste uma resposta diferente de 2xx, recuperação após tempo limite, um corpo adulterado e uma assinatura expirada. Utilize o período de tolerância e teste ambas as assinaturas antes de descartar o segredo do destinatário mais antigo.
Referência de integração: Sequência de testes recomendada
Tire o máximo proveito dessa capacidade.
Assine as famílias de eventos canônicos necessárias para o seu produto, em vez de cada entrada do catálogo sem um manipulador.
Alerte sua equipe sobre entregas repetidas com falha ou não entregues e mantenha um registro de reconciliação até o recurso atual.
Armazene as referências exatas da decisão e a explicação da sua própria ação para que a equipe de suporte possa comprovar o que o aplicativo fez.
Faça o teste antes de confiar nele.
Execute os cenários de Sandbox ou simulador compatíveis com este produto. Quando uma ferramenta for exclusiva para Produção, verifique primeiro o acesso e o escopo e, em seguida, use apenas um teste de Produção permitido e cuidadosamente revisado. Uma captura de tela da documentação ou o carregamento bem-sucedido de uma página não constituem um teste de integração de ponta a ponta.
Assinaturas adulteradas ou expiradas serão rejeitadas.
Um reenvio lógico desencadeia uma ação comercial.
A recuperação do receptor persiste mesmo após a reinicialização do processo.
Eventos atrasados não podem sobrescrever o estado mais recente.
O regime de rotação funciona durante todo o período de tolerância.
Solução de problemas
As assinaturas falham após a análise. JSON
Verificar bytes brutos antes da análise. Reserializado. JSON altera a entrada com sinal.
Um reenvio funcionou duas vezes.
Utilize o ID do evento lógico como chave única e durável em vez de deliveryId.
A entrega foi concluída com sucesso, mas a conta não sofreu alterações.
Inspecionar o processamento de negócios em fila e a correlação. HTTP A entrega não comprova o efeito colateral subsequente.
Abra as referências de configuração e integração.
Abra a ferramenta de painel de controle. (abre num novo separador)
Leia a referência de integração. (abre num novo separador)
Voltar para Soluções (abre num novo separador) . Escolha a funcionalidade que deseja ativar e siga o guia correspondente.
Fontes
Charles Archibong
Cofundador
Charles Archibong é cofundador da Toden. Ele escreve sobre verificação de identidade, tecnologia financeira e o trabalho prático de construção de serviços digitais confiáveis.
