Webhook receiver guide

A compliant receiver can be built from this page alone. The delivery contract is designed so you can verify authenticity, reject replays, and process exactly once.

1 · Verify the signature

Each delivery carries X-Norruva-Signature (V1) plus X-Norruva-Timestamp and X-Norruva-Signature-V2 (a timestamped HMAC over the raw body using your endpoint secret). Compute the HMAC over the raw request bytes and compare in constant time. Prefer V2.

2 · Enforce the replay window

Reject any delivery whose X-Norruva-Timestamp is more than 5 minutes from now — this defeats replayed captures even if a signature is valid.

3 · Dedupe by delivery id

The delivery id is stable across retries. Persist processed ids and treat a repeat as a no-op so retried deliveries never double-apply.

4 · Respond correctly so retries behave

• Return 2xx promptly once you've durably accepted the event (do the heavy work async).
• 4xx tells the platform not to retry — use it only for genuinely un-processable payloads.
• 5xx or a timeout triggers backoff retries with the same delivery id.

5 · Parse the envelope

{ "id": "<uuid>", "type": "product.published",
  "timestamp": "2026-07-20T12:00:00.000Z", "apiVersion": "2024-12-05",
  "data": { /* event-specific fields */ } }

Branch on type (only catalogue events); pin your parser to apiVersion so payload-shape changes are explicit. timestamp is the ISO 8601 occurrence time of the event (distinct from the per-delivery X-Norruva-Timestamp signing header).