Receiving webhooks

Qasimha sends a signed POST webhook to your endpoint whenever an order status changes, allowing your system to stay synchronized in real time without the need for continuous polling.

Use webhooks to immediately detect key order lifecycle events, including when a checkout is:

• Completed successfully
• Declined
• Expired

You will also receive notifications when an order-related action is recorded, such as:

• Shipment creation or updates
• Refunds
• Order cancellations

Each webhook payload includes the relevant order identifier, enabling your application to retrieve the latest order details and trigger the appropriate business workflows.

Before you start

Register an endpoint

Register in the Merchant Portal → Settings → Webhooks, or with the API (scope webhooks:manage):

• You can register up to 5 endpoints per account. Paused endpoints count toward the limit.
• Each endpoint has its own signing secret (whsec_...).
• Each endpoint can receive every event (leave out events) or only a list you choose.
• The URL must be public HTTPS, at most 1024 characters, with no user name, password or #fragment. Private or internal addresses are rejected (URL_PRIVATE). The same check runs again on every delivery, so a host that later resolves to a private address is not called.
• Register separate endpoints in UAT and production. Each environment has its own endpoints and secrets.
• Every route under /merchant/webhooks, including the reads, needs the webhooks:manage scope on an API key. In the portal, only an owner or admin can manage webhooks.
• Every change (create, update, delete, rotate, replay) is written to your account's audit log.

Create an endpoint

curl -X POST "https://api-uat.qasimha.com/api/v1/merchant/webhooks" \
  -H "X-Api-Key: $QASIMHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.example/webhooks/qasimha",
    "description": "Production store",
    "events": ["order.confirmed", "order.refunded", "order.partially_refunded"]
  }'

The response is 201 Created with code WEBHOOK_CREATED. secret appears in this response only. Store it in a secrets manager right away.

{
  "success": true,
  "uuid": "9b2016cc-4c8a-453a-9185-46220744cb18",
  "code": "WEBHOOK_CREATED",
  "message": "Webhook endpoint created",
  "data": {
    "id": "a81cce0b-35c7-45e0-a212-0c9f0969ddf4",
    "url": "https://shop.example/webhooks/qasimha",
    "description": "Production store",
    "events": ["order.confirmed", "order.refunded", "order.partially_refunded"],
    "isActive": true,
    "secret": "whsec_...b877",
    "secretHint": "b877",
    "previousSecretExpiresAt": null,
    "createdAt": "2026-09-25T23:42:29.5562693Z"
  },
  "errors": null
}

Endpoint fields

GET /api/v1/merchant/webhooks returns data as an array of these objects, newest first. GET /api/v1/merchant/webhooks/{id} returns one.

Update, pause or delete

PUT /api/v1/merchant/webhooks/{id} takes any of url, description, events and isActive. Fields you leave out keep their value. events: [] switches the endpoint to every event. The response code is WEBHOOK_UPDATED.

# Pause an endpoint during maintenance
curl -X PUT "https://api-uat.qasimha.com/api/v1/merchant/webhooks/a81cce0b-35c7-45e0-a212-0c9f0969ddf4" \
  -H "X-Api-Key: $QASIMHA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

Events that happen while an endpoint is paused are not queued for it. When you resume, read missed changes with the orders API.

DELETE /api/v1/merchant/webhooks/{id} removes the endpoint (code WEBHOOK_DELETED, data: null). Deliveries still waiting for a retry end as Failed.

Rotate the secret

POST /api/v1/merchant/webhooks/{id}/rotate-secret returns the endpoint with a new secret (code SECRET_ROTATED). For 24 hours, until previousSecretExpiresAt, every delivery is signed with both secrets. See Rotating the secret.

Send a test event

curl -X POST "https://api-uat.qasimha.com/api/v1/merchant/webhooks/a81cce0b-35c7-45e0-a212-0c9f0969ddf4/ping" \
  -H "X-Api-Key: $QASIMHA_API_KEY"

The response is 202 Accepted with code PING_QUEUED and data: { "eventId": "evt_...", "endpointId": "..." }. A signed ping event then arrives at the URL. The portal's Send test event button does the same. A ping is sent even to a paused endpoint.

Read the delivery log

curl "https://api-uat.qasimha.com/api/v1/merchant/webhooks/a81cce0b-35c7-45e0-a212-0c9f0969ddf4/deliveries?status=Failed&page=1&pageSize=20" \
  -H "X-Api-Key: $QASIMHA_API_KEY"

The response is data.data (rows, newest first) and data.pagination (totalItems, page, pageSize, totalPages). One row is one event sent to one endpoint, with all its attempts:

The delivery log keeps finished deliveries for 30 days.

Replay a delivery

curl -X POST "https://api-uat.qasimha.com/api/v1/merchant/webhooks/a81cce0b-35c7-45e0-a212-0c9f0969ddf4/deliveries/6e44f7d4-a878-4e1c-9148-e7f8745fb50d/replay" \
  -H "X-Api-Key: $QASIMHA_API_KEY"

The response is 202 Accepted with code DELIVERY_REPLAYED and the new delivery row (replayOfId set, attempts: 0). The original row is kept. The replay sends the same event, with the same id and body, and gets its own full set of retries. Use it after you fix your receiver.

With a server SDK

The server SDKs wrap every call above:

const endpoint = await qasimha.webhookEndpoints.create({
  url: 'https://shop.example/webhooks/qasimha',
  description: 'Production store',
  events: ['order.confirmed', 'order.refunded'], // omit, or [], for every event
});
await secrets.put('QASIMHA_WEBHOOK_SECRET', endpoint.secret); // whsec_..., shown once

await qasimha.webhookEndpoints.ping(endpoint.id);

const log = await qasimha.webhookEndpoints.listDeliveries(endpoint.id, { status: 'Failed', page: 1, pageSize: 20 });
await qasimha.webhookEndpoints.replayDelivery(endpoint.id, log.items[0].id);

Management errors

Events

• Each refund and each shipment is its own event, even when a second partial refund leaves the status unchanged.
• Events are created in the same database transaction as the order change, so you are never told about a change that was rolled back.
• You subscribe by event name. ping is always sent to the endpoint it targets, whatever events says.

Payload

Every delivery is a POST with Content-Type: application/json; charset=utf-8. The body is the same on every retry and replay of an event.

{
  "id": "evt_9f8c1d2e3a4b5c6d7e8f90a1b2c3d4e5",
  "type": "order.confirmed",
  "createdAt": "2026-09-25T09:30:00Z",
  "apiVersion": "v1",
  "orderId": "9a2e6c4b-1111-4c2d-8a1f-000000000001",
  "orderReferenceId": "MERCHANT-ORDER-12345",
  "status": "Confirmed",
  "amount": 1000.00,
  "currency": "SAR",
  "data": {
    "order": {
      "id": "9a2e6c4b-1111-4c2d-8a1f-000000000001",
      "orderReferenceId": "MERCHANT-ORDER-12345",
      "status": "Confirmed",
      "channel": "Online",
      "checkoutChannel": null,
      "totalAmount": 1000.00,
      "currencyCode": "SAR",
      "capturedAmount": 0,
      "refundedAmount": 0,
      "voidedAmount": 0,
      "instalments": 4,
      "createdAt": "2026-09-25T09:00:00Z",
      "confirmedAt": "2026-09-25T09:30:00Z"
    }
  }
}

The order snapshot is taken when the event happens. Read the order again before you act on it.

A ping body has no order fields:

{
  "id": "evt_a05fd3fddfea4ac8bf76a442e3cf441d",
  "type": "ping",
  "createdAt": "2026-09-25T23:42:32Z",
  "apiVersion": "v1",
  "data": { "endpointId": "a81cce0b-35c7-45e0-a212-0c9f0969ddf4" }
}

Headers

Delivery and retries

• Qasimha checks for new events every 5 seconds, so a delivery usually leaves within seconds of the change.
• Respond with a 2xx status within 15 seconds. Do the real work in the background.
• Only 2xx counts as success. Redirects (3xx) are not followed and count as a failure, so register the final URL.
• A delivery that fails (no 2xx, a timeout, or a connection error) is retried 5 times over about 24 hours, so it gets 6 attempts in total:

• After the sixth failure the delivery is Failed. It is not retried again unless you replay it.
• Each attempt is signed afresh with its own timestamp, so a late retry still passes the 5-minute check.
• The portal shows every attempt and lets you replay one.

Handling events correctly

1. Verify the signature first. Reject anything that fails with 400.
2. Respond 2xx right away, then process the event in the background.
3. Remove duplicates using the event id (or X-Qasimha-Event-Id). Retries and replays repeat it.
4. Events can arrive out of order. Don't assume the sequence.
5. Treat the event as a signal, not the source of truth. Read the order with GET /api/v1/merchant/orders/{orderId} before you ship or refund.
6. Answer 2xx to event types you don't handle, so they are not retried.

Idempotent handler

Record each event id once, inside the same transaction as the work it triggers. A unique key on the id makes a second delivery a no-op.

CREATE TABLE qasimha_webhook_events (
  event_id     TEXT PRIMARY KEY,
  event_type   TEXT NOT NULL,
  received_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

import express from 'express';
import Qasimha, { WebhookSignatureError } from '@qasimha/sdk';

const app = express();
const qasimha = new Qasimha({
  apiKey: process.env.QASIMHA_API_KEY!,
  webhookSecret: process.env.QASIMHA_WEBHOOK_SECRET,
});

// express.raw keeps the exact bytes Qasimha signed. Register it before any express.json().
app.post('/webhooks/qasimha', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = qasimha.webhooks.constructEvent(req.body, req.headers);
  } catch (error) {
    return res.sendStatus(error instanceof WebhookSignatureError ? 400 : 500);
  }
  res.sendStatus(200); // acknowledge first
  queue.add(event);    // process in the background
});

async function process(event) {
  await db.transaction(async (tx) => {
    const inserted = await tx.query(
      'INSERT INTO qasimha_webhook_events (event_id, event_type) VALUES ($1, $2) ON CONFLICT DO NOTHING',
      [event.id, event.type],
    );
    if (inserted.rowCount === 0) return; // already handled

    if (event.type === 'ping') return;
    const order = await qasimha.orders.get(event.orderId); // the source of truth
    switch (event.type) {
      case 'order.confirmed':
        await markPaid(tx, order);
        break;
      case 'order.declined':
      case 'order.cancelled':
      case 'order.expired':
      case 'checkout_link.expired':
        await releaseStock(tx, order);
        break;
      case 'order.refunded':
      case 'order.partially_refunded':
        await recordRefund(tx, order, event.amount);
        break;
      default:
        break; // other events: nothing to do
    }
  });
}

markPaid, releaseStock, recordRefund, queue and db stand for your own code.

Testing in UAT

1. Create a UAT secret key with webhooks:manage in https://portal-uat.qasimha.com.
2. Register your endpoint against https://api-uat.qasimha.com. Use a public HTTPS tunnel if your server runs on your machine.
3. Call POST /api/v1/merchant/webhooks/{id}/ping and check that your server returns 200 and the delivery shows Succeeded.
4. Run a test checkout and watch order.confirmed arrive. Then fulfil, refund or cancel it and watch the matching events.
5. Return 500 from your handler once, check the retry in the delivery log, then replay it.

Go-live checklist

• A production endpoint is registered in https://portal.qasimha.com (UAT endpoints and secrets do not carry over).
• The production whsec_... secret is in your secrets manager, not in code or logs.
• Signature verification uses the raw body and rejects failures with 400.
• Your handler answers within 15 seconds and processes in the background.
• Duplicate event ids are ignored.
• You re-read the order before you ship or refund.
• Someone checks the delivery log for Failed deliveries.

Troubleshooting

Related