Webhook Setup

Goal

Set up a webhook endpoint so SMS Pay can notify your backend when payment status changes. Merchant admins configure endpoints in the dashboard; developers implement the receiving route.

Add endpoint in dashboard

1. Open Dashboard -> Webhooks.
2. Click Add endpoint.
3. Enter your HTTPS endpoint URL, for example https://merchant.example.com/webhooks/sms-pay.
4. Choose the events this endpoint should receive.
5. Enter or generate a signing secret and store it in your backend environment.
6. Save the endpoint.
7. Click Verify.
8. Send a test event.

Production endpoints must use HTTPS.

Event selection

Subscribe to:

For most merchants, one endpoint subscribed to all six events is simplest.

Backend environment

SMS_PAY_WEBHOOK_SECRET=whsec_minimum_16_characters

Keep the secret private. Rotate it if it is exposed.

Signature verification

Verify X-Webhook-Signature against the raw request body before parsing JSON.

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.SMS_PAY_WEBHOOK_SECRET!;

function safeEqual(left: string, right: string) {
  const a = Buffer.from(left);
  const b = Buffer.from(right);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  "/webhooks/sms-pay",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body as Buffer;
    const signature = req.header("x-webhook-signature") ?? "";
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

    if (!safeEqual(signature, expected)) {
      return res.status(401).send("invalid signature");
    }

    const webhookId = req.header("x-webhook-id");
    const eventType = req.header("x-webhook-event");
    const payload = JSON.parse(rawBody.toString("utf8"));

    await saveWebhookOnce(webhookId, payload);

    if (eventType === "payment.paid") {
      await markOrderPaid({
        smsPayPaymentIntentId: payload.data.payment_intent_id,
        merchantReference: payload.data.merchant_reference,
      });
    }

    return res.status(200).send("ok");
  },
);

Payload fields

{
  "event": "payment.paid",
  "environment": "SANDBOX",
  "timestamp": "2026-05-05T10:01:00.000Z",
  "data": {
    "payment_intent_id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
    "amount": "500",
    "currency": "BDT",
    "customer_reference": "SP7A91BC2D0",
    "merchant_reference": "ORDER-10045"
  }
}

Use merchant_reference to find your order when available. Use payment_intent_id as the stable SMS Pay fallback.

Verify button

Verify checks whether your endpoint can receive SMS Pay verification requests. Verification is a setup health check; it does not prove your fulfillment logic is complete.

Test button

Test sends a selected event to your endpoint and records the delivery result. Use it to confirm:

• signature verification works
• endpoint returns 2xx
• your idempotency storage works
• your handler ignores non-paid events for fulfillment

Delivery inspection

Dashboard -> Webhooks shows delivery status, HTTP status, attempts, payload, response body, and retry state. Use this page when an order did not update in your system.

Any non-2xx response, timeout, or redirect counts as a failed attempt. SMS Pay retries failed deliveries 10 times over about 24 hours (30s, 1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 10h) and then marks the delivery FAILED. You can retry a failed delivery from the dashboard. Webhook URLs must be public HTTPS endpoints. Redirects are not followed, and private or internal addresses are rejected.