> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Como a Noxpay entrega atualizações de status de transação para o seu backend.

## 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 endpoint `GET` 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](/pt/api-reference/reference/transaction-object) para a estrutura completa do payload, e a referência de [Statuses](/pt/api-reference/reference/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.

| Recurso                                                 | Onde configurar                                                      |
| ------------------------------------------------------- | -------------------------------------------------------------------- |
| Crossramp Checkout                                      | Campo `webhook` no corpo da requisição `POST /v2/crossramp_checkout` |
| Conversions                                             | Campo `webhook` no corpo da requisição `POST /v2/rfq`                |
| Onramp para Conta Global / Onramp para Endereço Externo | Campo `webhook` na transação, definido quando ela é criada           |
| Offramp da Conta Global / Offramp de Endereço Externo   | Campo `webhook` na transação, definido quando ela é criada           |

Se nenhuma URL de webhook for fornecida na criação, nenhuma notificação é enviada para aquela transação.

<Note>
  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.
</Note>

***

## 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](/pt/api-reference/reference/webhook-signature) 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 response `2xx`, a Noxpay tentará entregar novamente. Certifique-se de que seu handler é idempotente — o mesmo payload pode ser entregue mais de uma vez.