​

Webhook Verification

• The exact signing algorithm and which body is signed
• All headers sent with the request
• Verification examples in Node.js, Python, Ruby, PHP, and Go using timing-safe comparison
• Retry semantics — when LaunchMyStore re-attempts a failed delivery

​

Signature spec

signature = base64( HMAC_SHA256( client_secret, raw_request_body ) )

• client_secret is the app’s secret returned by /apps/credentials on install. Treat it like a password — never embed it in client-side code.
• raw_request_body is the exact bytes of the HTTP request body as it appears on the wire. Do not parse-and-reserialize the JSON before computing — a single whitespace difference fails the check.
• base64 is standard (not URL-safe) base64 with +// and padding.

​

Headers

​

Verification examples

1. Read the raw body before any JSON parsing happens.
2. Compute the same HMAC.
3. Compare to the header using timing-safe comparison (not ==).

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// IMPORTANT: read the raw body so the HMAC matches.
app.use('/webhooks', express.raw({ type: 'application/json' }));

function verifyWebhook(req, clientSecret) {
  const headerHmac = req.headers['x-lms-hmac-sha256'];
  if (!headerHmac) return false;

  const computed = crypto
    .createHmac('sha256', clientSecret)
    .update(req.body) // req.body is a Buffer because of express.raw
    .digest('base64');

  // Buffers of different length crash timingSafeEqual — guard first.
  const a = Buffer.from(headerHmac, 'utf8');
  const b = Buffer.from(computed, 'utf8');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

app.post('/webhooks', (req, res) => {
  if (!verifyWebhook(req, process.env.CLIENT_SECRET)) {
    console.warn('[webhook] invalid signature');
    return res.status(401).send('Unauthorized');
  }

  const topic = req.headers['x-lms-topic'];
  const payload = JSON.parse(req.body.toString('utf8'));
  console.log(`[webhook] ${topic} for shop ${req.headers['x-lms-shop-domain']}`);

  // Always respond 200 quickly. Heavy work goes to a queue.
  res.status(200).send('OK');
});

​

Common verification pitfalls

​

Idempotency

const seen = new Map(); // delivery id -> processedAt

app.post('/webhooks', verifyAndDecodeMiddleware, (req, res) => {
  const id = req.headers['x-lms-webhook-id'];
  if (seen.has(id)) {
    // Already processed — return 200 immediately so we don't keep retrying.
    return res.status(200).send('OK (dedupe)');
  }
  // ... process payload ...
  seen.set(id, Date.now());
  res.status(200).send('OK');
});

​

Retry semantics

​

Status codes and retry behaviour

• 2xx: Delivery marked SUCCESS. No further attempts.
• 429 / 5xx: Delivery retried up to MAX_RETRIES (3) using the schedule above. After exhaustion: FAILED.
• 4xx (except 429): Treated as a permanent client error. No retry. The webhook is marked FAILED immediately. If your endpoint returns 400 for a transient parse error, you will silently miss that event — return 5xx for transient errors so the retries run.
• Network error / timeout: Treated the same as a transient failure and retried.

​

Timeout

app.post('/webhooks', (req, res) => {
  // 1. Verify
  if (!verifyWebhook(req, secret)) return res.status(401).send('Unauthorized');
  // 2. Enqueue
  queue.add('process-webhook', { body: req.body, headers: req.headers });
  // 3. Ack inside the 10-second budget
  res.status(200).send('OK');
});

​

IP allowlist

​

Testing webhooks

curl -X POST "https://api.launchmystore.io/api/v1/webhooks/{webhookId}/test.json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

​

See also