Signing & retries

HMAC-SHA256 verification, retry policy, and replay protection.

Signing — HMAC-SHA256

LMN signs every webhook with HMAC-SHA256 using a shared secret (Stripe-compatible scheme). Headers sent with each request:

POST https://your-app.example.com/webhooks/lmn HTTP/1.1
Content-Type: application/json
X-LMN-Event-Id: evt_01HXYZ...
X-LMN-Timestamp: 1714567890
X-LMN-Signature: t=1714567890,v1=5257a869e7ecebeda32a...

What’s signed

The signed payload is:

<timestamp>.<raw_request_body_bytes>

• <timestamp> is the value of X-LMN-Timestamp (Unix seconds as string).
• . is a literal period.
• <raw_request_body_bytes> is the exact bytes of the HTTP body — do not parse and re-stringify the JSON.

Then HMAC-SHA256 with the shared secret, hex-encoded.

Signature header format

t=<timestamp>,v1=<signature_hex>

The v1= prefix leaves room for future signature schemes (v2=, …) without breaking existing clients.

The header can carry more than one v1 entry. During the 1-hour grace window after a production secret rotation, we sign each delivery with both the new and the old key — new key first, old key last:

t=1714567890,v1=<new key>,v1=<old key>

Verify by accepting any v1 entry that matches the secret you hold. See Secret rotation.

Verification (Node.js)

import crypto from 'crypto';

function verifyLmnWebhook(rawBody, headers, secret) {
  const sigHeader = headers['x-lmn-signature'];
  const tsHeader = headers['x-lmn-timestamp'];
  if (!sigHeader || !tsHeader) return false;

  // Replay protection: reject events older than 5 minutes
  const ageSeconds = Math.abs(Date.now() / 1000 - parseInt(tsHeader, 10));
  if (ageSeconds > 300) return false;

  // Collect EVERY v1 entry — there is more than one during a rotation window.
  const entries = sigHeader.split(',').map(p => p.trim().split('='));
  const t = entries.find(([k]) => k === 't')?.[1];
  if (t !== tsHeader) return false;

  const signatures = entries.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (signatures.length === 0) return false;

  const expected = Buffer.from(
    crypto.createHmac('sha256', secret)
      .update(`${tsHeader}.${rawBody}`, 'utf8')
      .digest('hex'),
    'hex',
  );

  // Accept if ANY entry matches the secret you hold. No early return — compare
  // them all, timing-safely. (timingSafeEqual throws on a length mismatch, so
  // guard the length first for malformed input.)
  return signatures.reduce((ok, sig) => {
    const received = Buffer.from(sig, 'hex');
    const match =
      received.length === expected.length &&
      crypto.timingSafeEqual(expected, received);
    return ok || match;
  }, false);
}

Common pitfalls (verify in your stack):

• Many web frameworks parse JSON before middleware sees the raw body. Capture raw bytes before parsing (in Express: express.raw({ type: 'application/json' })).
• JSON.stringify(req.body) produces different bytes than what was sent (whitespace, key order, escaping). Don’t use it.
• String comparison (==) of signatures leaks timing info. Use timingSafeEqual or your stack’s equivalent.
• Assuming exactly one v1 entry. A single-entry parser still verifies correctly — but it constrains when you can swap secrets during a rotation. See Secret rotation.

Replay protection

Mechanism	Purpose
X-LMN-Timestamp 5-min window	Reject delayed/replayed requests.
X-LMN-Event-Id deduplication	Reject the same event delivered twice (e.g., on retry overlap).

Track received event_ids for at least 24 hours and reject duplicates. A simple Redis set with 24h TTL works.

Clock skew tolerance: 5 minutes. NTP-sync your servers if drift exceeds that.

This deduplication suppresses replays. A webhook re-sent via the console’s Replay action deliberately carries the same X-LMN-Event-Id as the original, so a handler that rejects seen ids will discard it before your business logic runs — you see nothing arrive, and Replay looks broken. Keep the dedupe (it is correct for retries); clear the id from your store or bypass the check while testing. See Replaying a webhook.

Retry policy (5 attempts)

Attempt	Delay
1	immediate
2	+1 minute
3	+15 minutes
4	+2 hours
5	+12 hours

Stops on 2xx (success) or 410 Gone (you say “stop sending”). After 5 failures, the event is marked delivery_failed — you can re-attempt it yourself from the console once your endpoint is fixed, without contacting LMN. See Replaying a webhook.

Per-attempt timestamp. Each retry generates a fresh X-LMN-Timestamp and re-signs with the new timestamp — so the 5-minute replay window applies to the delivery time, not the original event. A retry at +12h is still verifiable.

Secret rotation

Rotate your own webhook signing secret from the partner console — Webhooks → Production (or Sandbox). The new secret is shown once, at rotation time: LMN stores no readable copy and cannot show it to you again. Lose it and your only recourse is to rotate again.

Production rotation is deliberately hard to trigger by accident. It requires all three of:

Gate	What it means
Production access	Your account is approved for production. Trial (sandbox) accounts can rotate the sandbox secret only.
Step-up verification	A fresh one-time code, emailed when you start the rotation. Your login code does not authorize a rotation.
Typed confirmation	You type your partner id to confirm.

LMN staff can also rotate on your behalf if you ask — that path is an immediate cutover with no grace window, so it’s coordinated with you first.

The 1-hour dual-signature grace window

A rotation you run yourself against production does not cut over instantly. For 1 hour afterwards, every delivery is signed with both keys and X-LMN-Signature carries two v1 entries — the new key first, the old key last:

t=1714567890,v1=<new key>,v1=<old key>

After the hour, deliveries carry a single v1 entry, signed with the new key only.

No change on your side is required to survive a rotation. A verifier still holding only the old secret keeps passing for the full hour, including one using the single-entry Object.fromEntries parser — that parser takes the last v1 entry, which is the old key’s signature. You have the hour to deploy the new secret.

What to do, by parser

Your verifier	During the window	What to do
Accepts any v1 entry (the code above)	Old or new secret verifies	Deploy the new secret whenever you like.
Reads a single v1 entry (last one wins)	Only the old secret verifies	Keep the old secret until the hour is up, then deploy the new one. Swapping mid-window breaks verification until the window closes.

That second row is the reason to upgrade to the any-match parser: it decouples your deploy from our clock.

Sandbox has no grace window — a sandbox rotation is an immediate cutover. Nothing live depends on it, and it’s the environment to rehearse your handling in.

Endpoint registration

Phase 1 (pilot): webhook URLs are exchanged offline (one URL per environment) during onboarding.

Future: API-driven endpoint management (planned post-pilot).