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

A failure state carries a populated `error_message`; a waiting state does not.

Your webhook handler can reuse the same parsing logic as your polling or retrieval code: handle `status` and `substatus` exactly as you would in a GET response. Payloads from this channel carry `webhook_version: "v2"`.

Because a webhook arrives unsolicited, you cannot infer the resource type from an endpoint the way you can when polling. Correlate on `end2end` against the transaction you created, or branch on which attribute keys are present. `process` reports the current stage as `stage.state` and is not a resource type — some of its values are shared across products.

See the [Transaction Object](/api-reference/reference/transaction-object) for the full payload shape, and the [Statuses](/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 on the transaction, set when it is created        |
| Offramp from Global Account / Offramp from External Address | `webhook` field on the transaction, set when it is created        |

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

<Note>
  Onramps and offramps are read-only over the API — there is no `/v2/` route that creates one. Their `webhook` is set on whichever flow created the transaction, and the API is used to poll it afterwards.
</Note>

***

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

***

## Verifying signatures

Every standard webhook request is signed so you can confirm it actually came from Noxpay and wasn't tampered with in transit. See [Webhook Signature Validation](/api-reference/reference/webhook-signature) for the header format, the signing formula, and code samples in several languages.

***

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