Webhook security

Verifying a delivery, refusing a replay, and why your listener should do almost nothing.

A webhook endpoint is a URL on your infrastructure that anyone on the internet can POST to. The signature is what turns it into something only Nomi can drive.

  1. Read the raw body

    Before any JSON parsing. The signature covers the exact bytes sent.

  2. Recompute the HMAC

    HMAC-SHA256 over ${t}.${rawBody} with the endpoint's secret, compared with a timing-safe comparison.

  3. Check freshness

    Refuse a t older than about five minutes. The signature proves origin; the timestamp proves it is not a replay.

  4. Answer quickly, work later

    Acknowledge with a 2xx and do the real work on a queue. A listener that calls three internal services before answering is a listener that times out.

The code is in Webhooks, and it verifies exactly what the platform signs.

Handle duplicates

Deliveries are retried, so your listener will eventually see the same event twice. Key your processing on the event's id and make the handler idempotent — that is cheaper than making delivery exactly-once, which nobody can.

If the secret leaks

Rotate it. Whoever administers the organisation does that from the console, the new secret is shown once, and deliveries are signed with it from then on — so a secret that ended up in a log, a screenshot or a repository stops being able to forge anything.

Webhooks

The reference.

Data protection

What we hold.