Evento
Um registo de mudança num 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 fiável de estados e eventos entre sistemas: desde a criação da mensagem e verificação da assinatura até a confirmação de receção, o reenvio e a monitorização de erros.
Eventos
estados e alterações
Assinatura
verificação de autenticidade
Novas tentativas
reenvio
Monitorização
histórico e diagnóstico
Fluxo de eventos
Da criação à confirmação de receção
01
Criar um evento
Especificar o identificador, tipo, horário, objeto, estado e dados relacionados.
02
Assinar e enviar
Enviar o evento por HTTPS com uma assinatura e timeout limitado.
03
Confirmar a receção
Após a verificação, guardar o evento e devolver 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 a receção e aplicar cada evento apenas uma vez.
Confirmação de receção
O destinatário devolve uma resposta HTTP de sucesso depois de verificar e guardar o evento de forma fiável.
Recuperação
Reenvio e reconciliaçã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 encaminhamento, 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, ronda, pedido, 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 do pedido original, transação, sessão ou cadeia de ações relacionadas.
Contexto
Marca, projeto, mercado, ambiente, fornecedor e outros dados necessários para o encaminhamento correto.
Dados do evento
O conjunto mínimo de campos necessário para processar a alteração ou realizar um pedido posterior à API.
Assinatura e verificação
Verificação da autenticidade e integridade do evento
Antes de alterar os dados, o destinatário verifica a ligaçã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 do pedido antes de alterar o formato JSON.
02
Verificar o timestamp
Rejeitar o pedido 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 receção 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 fiá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
Umo operador pode reenviar um evento selecionado sem criar uma nova operação.
Monitorização da entrega
Acompanhar o número de tentativas, respostas, o erro mais recente e o horário da próxima entrega.
Alertas
Alertar a equipa 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 estados
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 repor um objeto num estado desatualizado quando um evento antigo chegar com atraso.
Permitir apenas transições válidas entre estados.
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 ligação cai ou a confirmação de receção não chega ao remetente.
Processamento fora de ordem
Um estado 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 pedidos 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.
Lista de verificação antes do lançamento
A entrega em produção é ativada após a verificação de segurança, proteção contra duplicidades, reenvio e monitorização de erros.
Os ambientes de teste e produção usam endpoints e segredos de assinatura diferentes.
A assinatura é verificada com base na mensagem original e na respetiva hora de criação.
O identificador do evento é armazenado e protege as operações contra execução mais de uma vez.
O destinatário devolve rapidamente uma resposta HTTP de sucesso depois de guardar 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 equipa de suporte.
Precisa configurar uma entrega fiável de eventos?
Envie a lista de eventos, os endpoints de receção e as regras de transição de estados. A APIACE ajudará a definir a estrutura das mensagens, a verificação de assinatura, o reenvio e a monitorização de erros.