Body structure (JSON)

QuickShop sends a POST with Content-Type: application/json. The top-level field is always event (not type), along with a timestamp and a data object whose contents depend on the event type.

{
  "event": "order.created",
  "timestamp": "2026-04-23T12:00:00.000Z",
  "data": {
    /* fields per event type - see table below */
  }
}

Headers

• • Content-Type: application/json
• • Custom headers configured on the webhook are merged into the request.
• • If a secret is configured, we also send X-Webhook-Signature: sha256=<hmac> (HMAC-SHA256 of the raw body using the secret - verify it on your end).
• • Test deliveries (the “Test” button in the dashboard) include X-Webhook-Event: <event> and X-Webhook-Test: true, and the body has "test": true at the top level.

Integration testing: the Webhooks page in the merchant admin has a Test ▾ dropdown listing every event the webhook is subscribed to. Picking an event POSTs a synthetic payload that matches production exactly (including the HMAC signature) - so you can verify your endpoint, parser, and signature check without making a real sale. The only difference is the "test": true flag.

Delivery logs: GET /api/v1/webhooks/{id}/deliveries returns recent delivery attempts. Each entry includes: request_body (the exact JSON we POSTed), status_code, response_body, error, duration_ms, and event_type - so you can verify exactly what was sent without merchant dashboard access.

data fields per event (primary)

data is not the full REST model of the order or product - for full details (line items, addresses, etc.) call the API with your X-API-Key, e.g. GET /api/v1/orders/{id} once you have the order id.

You can subscribe to all events with *in the webhook's events array (via the admin UI or the API).

Verifying the signature

Compute HMAC-SHA256 over the raw request body using the webhook secret. Compare it (constant-time) against the value in X-Webhook-Signature after the sha256= prefix.

// Node.js (Express)
import crypto from 'node:crypto';

app.post('/quickshop/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.header('X-Webhook-Signature') || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.QUICKSHOP_WEBHOOK_SECRET)
    .update(req.body)              // raw Buffer, NOT JSON.stringify
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end('bad signature');
  }

  const payload = JSON.parse(req.body.toString('utf8'));
  if (payload.test === true) {
    // synthetic test delivery - ack but skip side-effects
    return res.status(200).end();
  }

  switch (payload.event) {
    case 'order.paid':    /* ... */ break;
    case 'order.updated': /* inspect payload.data.changes */ break;
    case 'order.cancelled': /* ... */ break;
  }
  res.status(200).end();
});