Como os webhooks funcionam
A Noxpay envia um webhook para a URL configurada a cada transição de etapa de uma transação. O payload é idêntico ao que você receberia do endpointGET correspondente para aquele recurso — não há um formato separado de webhook para implementar.
Estado de falha carrega error_message preenchido; estado de espera não.
Seu handler de webhook pode reutilizar a mesma lógica de parse do seu código de polling ou consulta: trate status e substatus exatamente como faria em um response GET. Payloads deste canal carregam webhook_version: "v2".
Como o webhook chega sem ser solicitado, você não pode inferir o tipo de recurso a partir do endpoint, como faz no polling. Correlacione por end2end com a transação que você criou, ou ramifique por quais chaves de atributo estão presentes. process informa o estágio atual no formato estagio.estado e não é um tipo de recurso — alguns de seus valores são compartilhados entre produtos.
Consulte o Objeto de Transação para a estrutura completa do payload, e a referência de Statuses para todas as combinações possíveis de status / substatus por recurso.
Configurando uma URL de webhook
Os webhooks são configurados por transação no momento da criação. Não há uma URL de webhook global — cada transação carrega a sua própria.
Se nenhuma URL de webhook for fornecida na criação, nenhuma notificação é enviada para aquela transação.
Onramps e offramps são somente leitura na API — não existe rota
/v2/ que crie um. O webhook deles é definido no fluxo que criou a transação, e a API é usada para consultá-la depois.Chargebacks
Quando um chargeback é aberto contra um pagamento concluído, a Noxpay envia uma notificação de webhook para a URL registrada na transação original que gerou o chargeback. Nenhuma configuração adicional de webhook é necessária — desde que o pagamento de origem tinha uma URL de webhook, os eventos de chargeback serão entregues lá automaticamente.Verificando assinaturas
Toda requisição de webhook padrão é assinada para que você possa confirmar que ela realmente veio da Noxpay e não foi alterada no caminho. Consulte Validação de Assinatura de Webhook para o formato dos headers, a fórmula de assinatura e exemplos de código em várias linguagens.Confiabilidade
A entrega de webhooks é refeita em caso de falha. Se o seu endpoint não retornar um response2xx, a Noxpay tentará entregar novamente. Certifique-se de que seu handler é idempotente — o mesmo payload pode ser entregue mais de uma vez.