Signatures

Webhook signatures use HMAC-SHA256 over raw request body.

Headers

X-Polynion-Event-Id: evt_...
X-Polynion-Timestamp: 2026-06-18T00:00:00.000Z
X-Polynion-Signature: v1=...

Signing string

{timestamp}.{raw_body}

Signature format

v1={hex_hmac_sha256(secret, signing_string)}

Receiver requirements

• Use raw request body bytes.
• Verify signature before parsing business payload.
• Reject unsupported signature version.
• Reject timestamp skew greater than 5 minutes.
• After verification, deduplicate event_id under a durable unique constraint and acknowledge an already-committed duplicate with 2xx.

Minimum verification flow

1. Read raw body.
2. Read timestamp and signature headers.
3. Build signing string.
4. Compute HMAC with webhook secret.
5. Constant-time compare against provided signature.
6. Check timestamp skew.
7. Parse the envelope and verify its event_id matches X-Polynion-Event-Id.
8. In one durable transaction, insert the unique event_id and apply the business effect; if it already exists, skip the effect and return 2xx.