Skip to main content

​
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 for the full payload shape, and the 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. If no webhook URL is provided at creation, no notifications are sent for that transaction.
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.

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