Evento
Um registro de mudança em um pagamento, sessão de jogo, verificação KYC, bônus, perfil de jogador ou outro objeto.
Documentação / Webhooks
Webhooks e entrega de eventos
Configure a entrega confiável de status e eventos entre sistemas: desde a criação da mensagem e verificação da assinatura até a confirmação de recebimento, o reenvio e o monitoramento de erros.
Eventos
status e alterações
Assinatura
verificação de autenticidade
Novas tentativas
reenvio
Monitoramento
histórico e diagnóstico
Fluxo de eventos
Da criação à confirmação de recebimento
01
Criar um evento
Especificar o identificador, tipo, horário, objeto, status e dados relacionados.
02
Assinar e enviar
Enviar o evento por HTTPS com uma assinatura e timeout limitado.
03
Confirmar o recebimento
Após a verificação, armazenar o evento e retornar rapidamente uma resposta HTTP de sucesso.
04
Tentar novamente em caso de erro
Repetir a entrega com intervalos crescentes e manter os eventos não entregues para investigação.
Visão geral
Um webhook informa uma mudança de estado
O remetente pode repetir a entrega, portanto o destinatário deve verificar a origem, confirmar o recebimento e aplicar cada evento apenas uma vez.
Confirmação de recebimento
O destinatário retorna uma resposta HTTP de sucesso após verificar e armazenar o evento de forma confiável.
Recuperação
Reenvio e conciliação ajudam a restaurar os dados após indisponibilidade temporária de qualquer um dos sistemas.
Estrutura do evento
O que um evento deve conter
Uma estrutura de mensagem consistente simplifica a verificação, o roteamento, a proteção contra duplicidades e o suporte a diferentes tipos de eventos.
Identificador do evento
Um valor único usado pelo sistema para reconhecer reenvios e localizar o histórico de processamento.
Tipo de evento
Um nome claro e estável que define a alteração ocorrida e como ela deve ser processada.
Horário de criação
A data e a hora em que o evento foi criado, no formato e fuso horário acordados.
Objeto relacionado
O tipo e identificador do pagamento, jogador, rodada, solicitação, bônus ou outro objeto.
Versão do esquema
Um número de versão ajuda a alterar a estrutura da mensagem com segurança, sem interromper integrações ativas.
Correlação da operação
O identificador da requisição original, transação, sessão ou cadeia de ações relacionadas.
Contexto
Marca, projeto, mercado, ambiente, provedor e outros dados necessários para o roteamento correto.
Dados do evento
O conjunto mínimo de campos necessário para processar a alteração ou realizar uma requisição posterior à API.
Assinatura e verificação
Verificação da autenticidade e integridade do evento
Antes de alterar os dados, o destinatário verifica a conexão segura, a assinatura, o horário de criação e o identificador único do evento.
01
Capturar a mensagem bruta
Verificar a assinatura com base no corpo bruto da requisição antes de alterar o formato JSON.
02
Verificar o timestamp
Rejeitar a requisição se o horário do evento estiver fora da janela permitida.
03
Verificar a assinatura
Usar o segredo acordado e o algoritmo HMAC ou de assinatura digital.
04
Verificar o identificador
Confirmar que o evento ainda não foi aplicado e armazenar o resultado da verificação.
Entrega e novas tentativas
Respostas HTTP e reenvio
O remetente deve distinguir entre recebimento bem-sucedido, erro temporário e falha permanente, enquanto o destinatário deve responder de forma rápida e inequívoca.
Resposta HTTP de sucesso
Confirma que o evento foi verificado e armazenado de forma confiável para processamento posterior.
Timeout limitado
Não execute processamento demorado antes de responder ao remetente — primeiro armazene o evento.
Reenvio
Repetir a entrega após erro temporário de rede, indisponibilidade ou ausência de resposta.
Intervalo crescente entre tentativas
Aumentar gradualmente o intervalo entre as tentativas para evitar carga adicional.
Fila de eventos não entregues
Após esgotar todas as tentativas, manter o evento para diagnóstico e tratamento manual.
Reenvio manual
Uma operadora pode reenviar um evento selecionado sem criar uma nova operação.
Monitoramento da entrega
Acompanhar o número de tentativas, respostas, o erro mais recente e o horário da próxima entrega.
Alertas
Alertar a equipe quando os erros aumentarem, as tentativas se esgotarem ou os eventos se acumularem na fila.
Processamento de eventos
Proteção contra duplicidades e ordenação de status
O destinatário não deve depender de uma única entrega nem de uma ordem rígida de eventos.
Aplicar apenas uma vez
Armazenar o identificador do evento antes de alterar os dados.
Confirmar um evento repetido sem outro débito, crédito ou mudança de estado.
Vincular o evento ao objeto e ao seu estado atual.
Armazenar o evento e a alteração de negócio como uma única operação consistente.
Ordem e atualidade
Comparar timestamp, número de sequência ou versão do evento.
Não retornar um objeto a um estado desatualizado quando um evento antigo chegar atrasado.
Permitir apenas transições válidas entre status.
Em caso de dúvida, solicitar o estado atual do objeto pela API.
Testes
O que testar antes do lançamento
Testar entrega bem-sucedida, assinaturas inválidas, duplicidades, respostas lentas, eventos fora de ordem e recuperação após uma falha.
Assinatura inválida
Mensagem modificada, chave desconhecida, timestamp expirado e algoritmo não suportado.
Reenvio
O mesmo evento chega várias vezes antes e depois da conclusão do processamento.
Resposta lenta
O destinatário demora demais para responder, a conexão cai ou a confirmação de recebimento não chega ao remetente.
Processamento fora de ordem
Um status final chega antes de um intermediário, e um evento mais antigo é entregue depois de um mais novo.
Endpoint indisponível
Testar erros HTTP 5xx, DNS, TLS, limites de requisições e o esgotamento completo das tentativas.
Histórico de entrega
Todas as tentativas, respostas, erros e resultados de reenvio manual devem poder ser pesquisados pelo identificador do evento.
Checklist antes do lançamento
A entrega em produção é ativada após a verificação de segurança, proteção contra duplicidades, reenvio e monitoramento de erros.
Os ambientes de teste e produção usam endpoints e segredos de assinatura diferentes.
A assinatura é verificada com base na mensagem bruta junto com seu horário de criação.
O identificador do evento é armazenado e protege as operações contra execução mais de uma vez.
O destinatário retorna rapidamente uma resposta HTTP de sucesso após armazenar o evento.
Novas tentativas, intervalos crescentes e reenvio manual estão configurados.
O histórico de entrega e a pesquisa por identificador estão disponíveis para a equipe de suporte.
Precisa configurar uma entrega confiável de eventos?
Envie a lista de eventos, os endpoints de recebimento e as regras de transição de status. A APIACE ajudará a definir a estrutura das mensagens, a verificação de assinatura, o reenvio e o monitoramento de erros.