Receba um webhook uma única vez no seu sistema de negócio

Os eventos de devolução utilizam subscrições da Plataforma de programadores e o respetivo segredo de assinatura. Os callbacks de confirmação de endereço podem utilizar um segredo de assinatura por pedido. Não misture esses dois segredos. Subscreva os tipos exatos de evento disponíveis na Consola de programadores; não assuma que são suportadas subscrições com carateres universais.

Verificar antes de interpretar

A Alkax envia X-Alkax-Event-Id, X-Alkax-Timestamp (segundos Unix) e X-Alkax-Signature (v1= seguido de HMAC-SHA256 hexadecimal em minúsculas). A entrada assinada é a data/hora em UTF-8, um ponto e os bytes exatos do corpo em bruto do pedido. Utilize a cadeia do segredo de assinatura como chave HMAC. Não a descodifique de base64 nem volte a serializar o JSON antes. Rejeite datas/horas antigas utilizando uma janela de atualidade de cinco minutos, datas/horas futuras fora dessa janela, assinaturas malformadas e IDs de evento divergentes entre envelope e cabeçalho. Mantenha os relógios sincronizados. Utilize comparação em tempo constante.

Exponha o recetor através de um endpoint HTTPS público. A Alkax não envia para destinos de loopback, privados, link-local ou resolvidos pelo DNS para endereços privados e não segue redirecionamentos. Mantenha os segredos de assinatura fora do código-fonte, registos e configuração pública.

Cuidados com frameworks: o Express tem de capturar express.raw() antes do middleware JSON; o ASP.NET tem de colocar em memória/ler o corpo intocado do pedido antes da conversão do modelo; o Flask deve utilizar request.get_data() antes de interpretar; os proxies não podem reescrever os bytes do corpo. Encaminhe os três cabeçalhos Alkax. Nunca valide contra um conteúdo reformatado.

Aceitação duradoura e duplicados

Verifique primeiro. Numa única transação de base de dados, insira a identidade única composta pelo ambiente e evento com um hash do corpo em bruto e registe a ação de negócio ou coloque trabalho duradouro em fila. Confirme a transação antes de devolver 2xx. Uma falha após a confirmação mas antes da resposta provoca um duplicado: devolva 2xx sem repetir a ação apenas se o hash for idêntico. A mesma identidade de evento com um hash diferente constitui uma falha de integridade e não pode produzir efeitos. Consulte o estado canónico atual com a chave do ambiente antes de tomar decisões sensíveis à ordem. A ordem de entrega não é garantida. Conserve os registos de deduplicação pelo menos durante todo o período de reenvio suportado.

Não chame um serviço externo de reembolso dentro de um ciclo desprotegido de novas tentativas. Utilize a sua própria outbox transacional e contrato de idempotência. O return.received da Alkax representa a receção física, não uma autorização de reembolso.

Política de entrega

Ambos os emissores modernos de webhooks utilizam um tempo limite de dez segundos e até oito tentativas automáticas. As subscrições de projeto usam intervalos de 2, 4, 8, 16, 32, 64 e 128 minutos. Os callbacks por confirmação usam aproximadamente 1, 2, 4, 8, 16, 32 e 64 minutos, com variação aleatória. Estes calendários pertencem a emissores diferentes. As respostas 4xx sem sucesso são terminais, exceto 408, 425 e 429; as respostas 5xx e falhas de transporte são repetidas. Devolva 503 para uma falha transitória de armazenamento e 2xx para duplicados aceites de forma duradoura. Não devolva 200 antes de o armazenamento ser bem-sucedido. Assinaturas permanentemente incorretas exigem corrigir o segredo/tratamento do corpo antes do reenvio, não entregas repetidas às cegas.

Na Consola de programadores, inspecione o histórico de entregas da subscrição, corrija a causa e selecione Reenviar. O reenvio preserva o ID do evento e o conteúdo, mas assina com uma data/hora nova. A deduplicação tem, portanto, de usar o ID do evento, não a assinatura nem a data/hora.

Guarde os segredos das subscrições num gestor de segredos. A rotação de credenciais não substitui os segredos de webhooks. Para substituir o segredo de uma subscrição, crie a subscrição substituta, aceite ambos os segredos durante a transição, desative a subscrição antiga e reconcilie as entregas pendentes.

Tratamento do conteúdo

Um envelope de devolução tem eventId, type, occurredAt e data. Os dados contêm identificadores da devolução/expedição original, número de seguimento, estado de autorização/logística, motivo/tipo e hora do evento. Trate merchantReference como dados fornecidos pelo comerciante potencialmente sensíveis. Não registe o envelope completo. Este evento público de integração não contém acessos do destinatário, endereços precisos nem imagens de prova.

Alkax -> signed HTTPS webhook -> verify raw bytes -> durable inbox/work -> 2xx
                                      |
                                      +-> transient failure -> safe retry

Contratos de confirmação e recuperação

A API HTTP de confirmação, os callbacks anteriores por confirmação, os callbacks versionados por confirmação e as subscrições genéricas de projeto têm esquemas distintos:

Canal	Campos e estado
Resposta HTTP de confirmação autenticada	Campos camelCase, estado textual; instantâneo privado e deliveryInstructions; campos de utilização única a null nas consultas normais
Callback por confirmação v1 por omissão	Campos de topo eventId, type, occurredAt, request; campos internos PascalCase e estado numérico
Callback por confirmação v2 por adesão explícita	Campos de topo schemaVersion, eventId, type, occurredAt, request; apenas ID, referência, estado textual e validade do pedido em camelCase
Subscrição de projeto	Campos de topo eventId, type, occurredAt, data; dados de confirmação apenas com id, status numérico e expiresAt

O prefixo v1= do cabeçalho de assinatura designa o mecanismo HMAC; não seleciona o esquema JSON. Escolha o campo opcional callbackSchemaVersion ao criar uma nova confirmação. Os bytes do evento em fila e o esquema selecionado permanecem inalterados no reenvio. O reenvio manual por confirmação mantém o número total de tentativas; não promete um novo conjunto de oito tentativas.

Para recuperar após a perda de uma resposta, gere e cifre de forma duradoura um callbackSigningSecret opcional antes de criar a confirmação. Tem de conter exatamente 64 caracteres hexadecimais minúsculos gerados a partir de 32 bytes aleatórios, com um callbackUrl configurado. O HMAC utiliza o texto do segredo em UTF-8. A Alkax nunca devolve um segredo fornecido pelo chamador. Se for omitido, a Alkax gera um webhookSigningSecret e devolve-o apenas na resposta inicial de criação. Não existe endpoint de rotação nem de fornecimento posterior do segredo.

Uma repetição idêntica da criação devolve o pedido original, com recipientUrl e os campos de segredo de utilização única a null, mesmo após o prazo original da ligação. Preserve o conteúdo e a chave exatos e utilize uma nova referência opaca numa nova tentativa. Valide a identidade do evento no cabeçalho e no corpo, associe-o à tentativa local atual, guarde o ambiente e o ID do evento com um hash do corpo e reconcilie através de GET canónico autenticado. A expiração da ligação não invalida instantâneos concluídos; a validade do consentimento e da divulgação pertence à aplicação consumidora.

As respostas de teste e do histórico de entregas do projeto expõem apenas metadados de entrega explicitamente permitidos. Conteúdos em bruto, excertos de resposta do recetor e falhas em texto livre são excluídos para todos os papéis do projeto. Os eventos históricos de confirmação de projeto que não sejam seguros são retirados antes do envio e o seu reenvio manual é recusado; os segredos históricos retidos continuam a exigir correção operacional de âmbito delimitado. Isto não substitui capacidades de acesso nem segredos anteriormente expostos.

As notificações de confirmação Sandbox são guardadas num destino de teste em vez de enviadas às caixas de correio de destinatários reais, e todas as operações de confirmação estão limitadas ao projeto e ambiente. Implemente a versão compatível do fornecedor antes de utilizar estas adições. Consulte o contrato de callback recuperável para o exemplo exato de conteúdo e os requisitos restantes de lançamento. A interface privada alojada do VolXpr, o percurso de autorização duradoura e o trabalho completo de concorrência do ciclo de vida continuam separados.