API docs
Sous Chef Ordering API
Request access

Verifying webhook signatures

A webhook url is not a secret. Anyone who learns it can send a POST to it, and a request body alone does not prove who sent it. Every delivery to your channel therefore carries a signature. Verify it before you act on a delivery.

X-SousChef-Signature: v2=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...

Every delivery also carries the same values under X-OneTablet-Signature and X-OneTablet-Timestamp, for backward compatibility.

The header value is a comma-separated list of <scheme>=<value> parts. Use the part that starts with v2= and ignore any part you do not recognise.

The v2 value is a standard JWT, signed with a private key that we hold and verified with a public key that you fetch from us. You hold nothing that can produce a signature.

What is signed

The JWT is a detached signature. It does not contain the event. Your request body is the JSON envelope described in Webhooks, and the token is bound to that body by a hash:

ClaimValue
isshttps://api.onetablet.com
iatwhen the delivery was signed, in Unix seconds
nbfequal to iat
expiat + 300, the end of the replay window
jtithe envelope's id, the same value you deduplicate on
body_sha256unpadded base64url SHA-256 of the raw request body

The JWT header carries:

HeaderValue
algES256 (ECDSA P-256 with SHA-256)
kidwhich of our published keys signed this delivery
typJWT

body_sha256 covers the raw body, not a re-serialization of it. Hash the exact bytes you received, before you parse the JSON. If you parse the body and serialize it again, key order, whitespace and escaping can change, and the hash no longer matches. Read the raw body, verify, and parse only after that.

Verifying the JWT without comparing body_sha256 does not verify the delivery. The token alone would then authenticate any body for the next five minutes.

The public keys

https://api.onetablet.com/.well-known/onetablet-webhook-jwks.json

This is a standard JWKS document. Give the URL to your JWT library, for example createRemoteJWKSet in Node's jose, PyJWKClient in PyJWT, jwks-rsa, or JWK::parseKeySet in firebase/php-jwt. The library resolves the token's kid to a key, caches the result, and fetches the document again when it meets a kid it has not seen.

Do not copy a key from that document into your configuration. When we rotate keys, a library that reads the URL follows the change without any action from you. A pinned copy stops verifying.

The document can be cached for five minutes.

The replay window

A delivery is valid for 300 seconds from iat, expressed as nbf and exp, so your JWT library enforces the window for you.

Allow about 60 seconds of clock tolerance (clockTolerance: 60 in jose). Keep your host's clock synchronised with NTP. If the clock is minutes off, every delivery looks expired.

A delivery that you reject because of the clock counts as a failed attempt and is retried, like any other failure. See Webhooks → Retries.

A Node example

The example uses Express and keeps the raw body. The express.raw() middleware matters: the default express.json() parses the body and discards the bytes that you need.

const crypto = require('node:crypto');
const express = require('express');
const { createRemoteJWKSet, jwtVerify } = require('jose');

const SOUS_CHEF_JWKS_URL = 'https://api.onetablet.com/.well-known/onetablet-webhook-jwks.json';
const SOUS_CHEF_ISSUER = 'https://api.onetablet.com';

// Build this once, at startup. It owns the key cache. Rebuilding it for each request
// fetches the JWKS on every delivery.
const JWKS = createRemoteJWKSet(new URL(SOUS_CHEF_JWKS_URL));

async function verifyDelivery(rawBody, signatureHeader) {
  // The header is a comma-separated list of scheme parts. Take the v2 part.
  const part = (signatureHeader || '')
    .split(',')
    .map((s) => s.trim())
    .find((s) => s.startsWith('v2='));
  if (!part) return null;

  // The library checks the signature, the issuer and the nbf/exp replay window.
  const { payload } = await jwtVerify(part.slice('v2='.length), JWKS, {
    issuer: SOUS_CHEF_ISSUER,
    algorithms: ['ES256'], // always pin the algorithm; never trust the token's own alg
    clockTolerance: 60,
  });

  // The signature is detached, so this step ties it to the bytes you received.
  const expected = crypto.createHash('sha256').update(rawBody).digest('base64url');
  const claimed = Buffer.from(String(payload.body_sha256 || ''), 'utf8');
  const actual = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on a length mismatch, so check the length first.
  if (claimed.length !== actual.length) return null;
  if (!crypto.timingSafeEqual(claimed, actual)) return null;

  return payload;
}

const app = express();

app.post('/webhooks/sous-chef', express.raw({ type: 'application/json' }), async (req, res) => {
  let claims;
  try {
    claims = await verifyDelivery(req.body, req.get('X-SousChef-Signature'));
  } catch {
    claims = null; // jose reports every failure as a throw
  }

  if (!claims) {
    // A 401 counts as a failed attempt, and the delivery is retried.
    return res.status(401).send('invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8')); // parse only after verifying

  // Acknowledge first and process asynchronously. You have 30 seconds to answer.
  res.status(200).send();
  handleAsync(event);
});

The same steps apply in any language: read the raw bytes, verify the JWT against the JWKS with a pinned algorithm, then compare body_sha256 with a SHA-256 of those bytes.

Always pass algorithms: ['ES256']. A verifier with no algorithm allow-list accepts whatever algorithm the token itself names, which lets a forged token pass.

Key rotation

Key rotation needs no action from you. We publish the new key in the JWKS, then start signing with it. Your library meets an unfamiliar kid, fetches the document again, and continues. Both keys stay published during the overlap, so deliveries signed with the previous key still verify.

Troubleshooting

SymptomLikely cause
Every delivery fails on body_sha256You are hashing a re-serialized body. Capture the raw bytes before parsing.
Every delivery fails after a period of workingA key was pinned locally instead of read from the JWKS URL, and it was rotated.
Every delivery looks expiredYour host's clock is not synchronised, or no clockTolerance is set.
no applicable key found in the JSON Web Key SetThe JWKS cache is stale, or the key set is rebuilt for each request.
The signature verifies but the delivery is wrongbody_sha256 is not compared, or it is compared against a parsed body.
The header does not parseYou are matching the whole header. Split on , and take the v2= part.
RangeError from timingSafeEqualThe length check before the comparison is missing.

Signing is not deduplication

A signature authenticates a delivery. It does not identify an event. An event can be delivered more than once, and the same event delivered twice is signed twice, with two different iat values and two different tokens. Deduplicate on the envelope's id, which is also the token's jti, as described in Webhooks. Never deduplicate on the signature.