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

> How Noxpay delivers transaction status updates to your backend.

## How webhooks work

Noxpay sends a webhook to your configured URL at every stage transition of a transaction. The payload is identical to what you would receive from the corresponding `GET` endpoint for that resource — there is no separate webhook format to implement.

Your webhook handler can reuse the same parsing logic as your polling or retrieval code. Parse the `template` field to know which resource type the payload represents, then handle `status` and `substatus` as you would in a GET response.

See the [Transaction Object](/noxpay-docs-v2/api-reference/reference/transaction-object) for the full payload shape, and the [Statuses](/noxpay-docs-v2/api-reference/reference/statuses) reference for all possible `status` / `substatus` combinations per resource.

***

## Configuring a webhook URL

Webhooks are set **per transaction** at creation time. There is no global webhook URL — each transaction carries its own.

| Resource                                                    | Where to set it                                                   |
| ----------------------------------------------------------- | ----------------------------------------------------------------- |
| Crossramp Checkout                                          | `webhook` field in the `POST /v2/crossramp_checkout` request body |
| Conversions                                                 | `webhook` field in the `POST /v2/rfq` request body                |
| Onramp to Global Account / Onramp to External Address       | `webhook` field when creating the transaction via API             |
| Offramp from Global Account / Offramp from External Address | `webhook` field when creating the transaction via API             |

If no webhook URL is provided at creation, no notifications are sent for that transaction.

***

## Chargebacks

When a chargeback is raised against a completed payment, Noxpay sends a webhook notification to the URL registered on the **original transaction** that generated the chargeback. No separate webhook configuration is needed — as long as the originating payment had a webhook URL, chargeback events will be delivered there automatically.

***

## Reliability

Webhook delivery is retried on failure. If your endpoint does not return a `2xx` response, Noxpay will retry the delivery. Make sure your handler is idempotent — the same payload may be delivered more than once.