> ## 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.

Seu handler de webhook pode reutilizar a mesma lógica de parse do seu código de polling ou consulta. Parse o campo `template` para saber qual tipo de recurso o payload representa, depois trate `status` e `substatus` como faria em um response GET.

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` ao criar a transação via API                         |
| Offramp da Conta Global / Offramp de Endereço Externo   | Campo `webhook` ao criar a transação via API                         |

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

***

## 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.

***

## 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.