Verify Webhook Signatures
Verify Agiled webhook requests with HMAC signatures.
Agiled signs webhook deliveries with the secret shown when you create the subscription.
Verify every webhook before trusting the event. A valid signature proves the payload came from Agiled and was not changed in transit.
Headers
Webhook requests include:
X-Agiled-Webhook-EventX-Agiled-Webhook-IdX-Agiled-Webhook-SignatureX-Agiled-Webhook-Timestamp
Signature Input
Agiled signs:
timestamp.raw_json_payloadusing HMAC-SHA256 and the webhook subscription secret.
Use the exact raw JSON payload bytes received by your server. Re-serializing or pretty-printing JSON before verification will produce a different signature.
Verification Checklist
- Read the raw request body before parsing JSON.
- Read
X-Agiled-Webhook-Timestamp. - Build
timestamp + "." + rawBody. - Compute an HMAC-SHA256 hex digest with the webhook secret.
- Compare it to
X-Agiled-Webhook-Signatureusing a timing-safe comparison. - Reject stale timestamps according to your security policy.
After verification succeeds, store the webhook ID or event ID you use for idempotency. This prevents duplicate processing when a delivery is retried.
Common Verification Mistakes
- Parsing JSON before saving the raw body.
- Using the wrong subscription secret.
- Comparing signatures with a normal string comparison.
- Ignoring stale timestamps.
- Rebuilding the payload with different whitespace or key order.
Failed Verification Response
Return a non-2xx response when signature verification fails. Do not process,
store as trusted, or forward the event to internal systems when the signature,
timestamp, or secret is invalid.
Log enough context to debug safely: delivery ID, event type, timestamp, and failure reason. Do not log the webhook secret or full sensitive payload unless your security policy allows it.
Secret Rotation
Rotate webhook secrets when a receiver is rebuilt, a vendor changes, or a secret may have been exposed. Create a new subscription or secret, deploy the receiver configuration, confirm one signed delivery succeeds, then remove the old subscription.
Keep rotation steps documented with the receiver owner so production incidents do not depend on one person's memory.