Webhook events
A webhook is an HTTP POST that NogorPay sends to your server when a charge changes state. Webhooks let you mark orders as paid even if the customer closes their browser before returning to your site.
Set up webhooks
Section titled “Set up webhooks”- In the dashboard, open Integrations → Connection settings and add your domain under Allowed Webhook Domains, for example
yourstore.com. Subdomains such asapi.yourstore.comare allowed automatically. - Pass
webhook_urlwhen you create a charge. - On your server, accept
POSTrequests at that URL, verify the signature, and return a2xxstatus.
Event types
Section titled “Event types”| Event | Sent when |
|---|---|
charge.completed |
The payment was confirmed. Fulfil the order. |
charge.cancelled |
The customer cancelled on the checkout page. |
NogorPay doesn’t send a webhook when a checkout expires. To detect expiry, compare the charge’s expires_at with the current time, or call Verify a charge.
Request headers
Section titled “Request headers”| Header | Example | Description |
|---|---|---|
Content-Type |
application/json |
The body is JSON. |
User-Agent |
NogorPay-Webhooks/1.0 |
Identifies NogorPay. |
NOGORPAY-EVENT |
charge.completed |
The event type. Same as event in the body. |
NOGORPAY-SIGNATURE |
sha256=5d41402abc4b2a76... |
HMAC-SHA256 of the raw body. See Verify signatures. |
NOGORPAY-ATTEMPT |
1 |
Delivery attempt number, from 1 to 4. |
Payload
Section titled “Payload”{ "event": "charge.completed", "invoice_id": "INV-7K9X2P8M", "order_id": "ORDER-1042", "session_id": "cs_live_3f2a9c0e8b7d4e1fa6c5b4d3e2f1a0b9", "status": "completed", "amount": 1500, "currency": "BDT", "payment_method": "bkash", "trx_id": "9B7X2K4L", "customer": { "name": "Rahim Ahmed", "phone": "01712345678", "email": "customer@example.com" }, "metadata": { "cart_id": "c_981", "websiteDomain": "yourstore.com" }, "created_at": "2026-08-07T12:00:00.000Z", "completed_at": "2026-08-07T12:03:41.000Z"}{ "event": "charge.cancelled", "invoice_id": "INV-7K9X2P8M", "order_id": "ORDER-1042", "session_id": "cs_live_3f2a9c0e8b7d4e1fa6c5b4d3e2f1a0b9", "status": "cancelled", "amount": 1500, "currency": "BDT", "payment_method": null, "trx_id": null, "customer": { "name": "Rahim Ahmed", "phone": "01712345678", "email": "customer@example.com" }, "metadata": { "cart_id": "c_981", "websiteDomain": "yourstore.com" }, "created_at": "2026-08-07T12:00:00.000Z", "completed_at": null}Payload fields
Section titled “Payload fields”| Field | Type | Description |
|---|---|---|
event |
string | charge.completed or charge.cancelled. |
invoice_id |
string | NogorPay invoice ID. |
order_id |
string or null |
The order_id you sent when creating the charge. |
session_id |
string | Checkout session ID. |
status |
string | completed or cancelled. |
amount |
number | Charge amount in BDT. |
currency |
string | Always BDT. |
payment_method |
string or null |
Provider the customer paid with. |
trx_id |
string or null |
Transaction ID from the provider. |
customer.name |
string or null |
Customer’s name. |
customer.phone |
string or null |
Customer’s phone. |
customer.email |
string or null |
Customer’s email. |
metadata |
object or null |
The metadata you sent, plus fields NogorPay adds such as websiteDomain. |
created_at |
string | When the charge was created. |
completed_at |
string or null |
When the payment was confirmed. null unless completed. |
Responding and retries
Section titled “Responding and retries”Return any 2xx status within 10 seconds to acknowledge the webhook. The response body is ignored.
NogorPay retries a delivery when your server times out, can’t be reached, or returns 408, 425, 429 or any 5xx status. Other 4xx statuses are not retried.
| Attempt | Sent after the previous attempt | Timeout |
|---|---|---|
| 1 | Immediately | 10 s |
| 2 | 1 minute | 20 s |
| 3 | 5 minutes | 20 s |
| 4 | 10 minutes | 20 s |
Best practices
Section titled “Best practices”- Verify the signature before you trust the payload.
- Check the amount against your order total before you fulfil it.
- Respond quickly. Return
200first, then do slow work (emails, stock updates) in a background job. - Have a fallback. If you don’t receive a webhook, call Verify a charge.
