The most common support question for any payment integration is some version of "the customer paid but my order didn't update". Almost every time, the cause is the webhook handler. Here's a checklist that avoids those problems.
1. Verify the signature, always
Your webhook URL is public. Anyone who finds it can send a fake "payment.success". Every UPIstar webhook carries an X-UPIstar-Signature header, an HMAC-SHA256 of the raw body signed with your secret. Compute it yourself and compare in constant time.
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))) return res.sendStatus(401);
Use the raw body bytes. If your framework parses JSON first and you re-serialise it, the signature won't match.
2. Make the handler idempotent
Networks are unreliable, so webhooks are delivered at least once, not exactly once. Before fulfilling an order, check whether it's already marked paid. If so, return 200 and do nothing else. A unique constraint on the UTR in your database is a cheap extra safety net.
3. Respond fast, process later
Return a 2xx within a few seconds. If fulfilment involves sending emails, generating PDFs or calling other APIs, put that work on a queue. Slow handlers time out, trigger retries, and multiply your load.
4. Check the amount and order
Even with a valid signature, confirm that the order_id exists in your system and the amount matches what you expected. It's a sensible defence-in-depth step, and it catches bugs in your own order creation.
5. Have a fallback
If your server was down for a while, don't rely on retries alone. Run a small job that calls GET /orders/{id} for orders still pending after a few minutes. Between retries, the status endpoint and the dashboard's webhook replay, no payment should go unconfirmed.
6. Log everything
Store the raw payload, signature result and your response for every webhook. When a customer calls, you'll be able to answer in seconds. UPIstar keeps a delivery log on its side too, so you can compare.
Quick checklist
- ☐ Signature verified with raw body and constant-time compare
- ☐ Duplicate deliveries handled gracefully
- ☐
2xxreturned in under 10 seconds - ☐ Order ID and amount cross-checked
- ☐ Fallback status polling for stale pending orders
- ☐ Payloads and responses logged
Full details are in the webhook documentation.