Webhook Security

You should never trust a webhook payload merely because it was sent to your URL. Forge provides three layers of verification to ensure authenticity and integrity.

Signature

HMAC-SHA256 hash ensuring the body hasn't been tampered with.

Replay Guard

Timestamp validation prevents replay attacks.

HTTPS Only

Payloads are strictly delivered over TLS.

1. Validating Signatures

Every request includes the X-Forge-Signature header. This is a hex-encoded HMAC-SHA256 hash generated using your unique Webhook Secret.

The construction

Signature = HMAC_SHA256( secret, "timestamp.raw_body" )

Note: You must use the raw request body string. If your framework parses JSON automatically (like Express `body-parser`), the signature check will fail because whitespace/formatting differences change the hash.

2. Replay Protection

The X-Forge-Timestamp header contains the Unix timestamp (seconds) when the event was sent. To prevent malicious actors from intercepting a valid request and re-sending it later:

  • Calculate the difference between your server's current time and the header timestamp.
  • If the difference is greater than 300 seconds (5 minutes), reject the request.

3. Secret Rotation

If you suspect your webhook secret has been compromised:

  1. Navigate to Dashboard → Settings → Webhooks.
  2. Click Rotate Secret.
  3. Immediately update your application environment variables with the new secret.
  4. Old secrets expire immediately. Expect a brief period of failed signature checks during deployment.