Ordexs API v1 Get an API key

Webhooks

Verifying signatures

Every webhook is signed with your endpoint's secret. Check the signature before you trust a single byte of the payload.

Why

Your webhook URL is public. Anyone who finds it can post JSON to it. The signature proves a request came from Ordexs, for your endpoint, and wasn't changed on the way.

The signature header

Ordexs-Signature: t=1760177100,v1=5f2b9c…e41a
  • t is the Unix time the request was signed.
  • v1 is a hex HMAC-SHA256 of the string <t>.<raw body>, keyed with the endpoint's secret (whsec_…).
  • During a secret rotation there are two v1 entries, one per secret. Accept the request if any of them matches.

Checking it

  1. Read the raw request body, exactly as received. Parse JSON only after verifying: re-serialising changes the bytes and the signature won't match.
  2. Split the header on , and each part on the first =.
  3. Reject the request if t is more than 5 minutes from your clock. This stops someone replaying an old request.
  4. Compute HMAC-SHA256 of t + "." + raw body with your secret, as lowercase hex.
  5. Compare it to each v1 with a constant-time comparison. If none matches, answer 400 and stop.
import crypto from 'node:crypto'

export function verifyOrdexsSignature(rawBody, header, secret, toleranceSeconds = 300) {
  let t = 0
  const signatures = []
  for (const part of (header ?? '').split(',')) {
    const i = part.indexOf('=')
    const key = part.slice(0, i).trim()
    const value = part.slice(i + 1).trim()
    if (key === 't') t = Number(value)
    else if (key === 'v1') signatures.push(value)
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return signatures.some(
    (sig) => sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
  )
}

// Express: keep the body raw for this route.
app.post('/webhooks/ordexs', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8')
  if (!verifyOrdexsSignature(raw, req.get('Ordexs-Signature'), process.env.ORDEXS_WEBHOOK_SECRET)) {
    return res.status(400).send('Bad signature')
  }
  const event = JSON.parse(raw)
  queue.add(event) // do the work later
  res.sendStatus(200)
})

Common mistakes

  • Verifying the parsed body. Frameworks that parse JSON for you (Express's express.json(), Laravel's $request->all()) give you a re-built object. Use the raw bytes.
  • A clock that drifts. Keep your server on NTP; a clock more than 5 minutes off rejects every event.
  • Checking only the first v1. During a rotation the matching signature may be the second one.
  • Trimming or re-encoding the body in a proxy in front of your app. Pass it through untouched.