Verify signatures
Verify the raw body and timestamp using the endpoint signing secret.
RevKeen signs deliveries with HMAC-SHA256. Use the endpoint signing secret; a merchant API key is not a webhook signing secret.
Header and signed bytes
X-Revkeen-Signature: t=1788566400,v1=<hex-encoded-hmac>X-Revkeen-Signature is the only signature header.
Header names are case-insensitive; use x-revkeen-signature consistently in new integrations.
The signature is hex-encoded HMAC_SHA256(secret, timestamp + "." + rawBody).
Do not parse and re-serialize JSON before verification. Keep the clock synchronised
and enforce timestamp tolerance (300 seconds in the example).
Recommended receiver
Use the complete Node.js receiver. It verifies the signature,
validates the envelope, and persists the event before 202. Invalid signatures return
400; storage failures return 503.
For full events, constructEvent verifies and parses in one call. For truncated
references, verify the raw signature before handling the reference. The published
WebhookSignatureVerificationError has a message but no code property.
Manual verification
If you cannot use an SDK, implement and test every step:
- Read the unmodified body and parse
tandv1from the header. - Reject malformed or missing values.
- Compute HMAC over the timestamp and raw body using the endpoint secret.
- Compare using a constant-time cryptographic comparison.
- Enforce a replay window and reject implausible future timestamps.
- Parse and validate the event only after verification succeeds.
Ordinary shell string equality is not constant-time verification. A library implementing another provider's format is not automatically compatible with RevKeen.
Replay and rotation
Timestamp checks limit replay age but do not prevent duplicates within the window. Use the durable inbox and business idempotency. Retries are signed again; event creation time is not the signature timestamp.
Follow the rotation procedure. The current API replaces the secret; do not assume a grace period. Never commit signing secrets or send them to support.
Common failures
| Symptom | Check |
|---|---|
| Every signature fails | Correct endpoint secret and unmodified body |
| Missing header | Proxy and framework preserve the signature header |
| Failure after rotation | Replacement secret and in-flight attempts |
| Old timestamp | Server clock, delayed processing, or replayed fixture |
| Valid signature, invalid payload | Full versus truncated envelope and event schema |
Continue with delivery and retries.
API reference for this workflow
Owner: david · Reviewed 5 Sep 2026