Skip to content

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.

  1. In the dashboard, open Integrations → Connection settings and add your domain under Allowed Webhook Domains, for example yourstore.com. Subdomains such as api.yourstore.com are allowed automatically.
  2. Pass webhook_url when you create a charge.
  3. On your server, accept POST requests at that URL, verify the signature, and return a 2xx status.
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.

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.
{
"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"
}
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.

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
  • Verify the signature before you trust the payload.
  • Check the amount against your order total before you fulfil it.
  • Respond quickly. Return 200 first, 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.