Skip to main content

Signature Verification

Monk signs all webhook payloads so you can verify they originated from us. Always verify signatures before processing webhook data.

How Signatures Work

Each webhook includes an X-Monk-Signature header with this format:
The signature is computed over:

Verification Steps

  1. Extract t (timestamp) and v1 (signature) from the header
  2. Check that the timestamp is within your tolerance window (e.g., 5 minutes)
  3. Compute the expected signature: HMAC-SHA256(secret, "{t}.{payload}")
  4. Compare signatures using constant-time comparison
Prevent replay attacks: Reject webhooks where the timestamp (t) is older than your tolerance window (recommended: 300 seconds).

Code Examples

Common Errors

Invalid Signature

The computed signature doesn’t match. Common causes:
  • Using the wrong signing secret (each endpoint has a unique secret)
  • Parsing or modifying the payload before verification
  • Encoding issues with the payload
Always verify against the raw request body before JSON parsing.

Timestamp Too Old

The webhook timestamp is outside your tolerance window. This could indicate:
  • A replay attack attempt
  • Significant clock skew between your server and Monk
  • A delayed retry being delivered

Missing Signature Header

The X-Monk-Signature header is missing. Ensure:
  • You’re receiving the request at the correct endpoint
  • Your proxy/load balancer isn’t stripping headers

Testing Webhooks

Local Development

Use a tunneling service to test webhooks locally:
  1. Start your local server
  2. Create a tunnel: ngrok http 3000
  3. Add the tunnel URL as a webhook endpoint in Monk
  4. Trigger events in your Monk sandbox

Webhook Logs (Coming Soon)

View delivery attempts and responses in Settings → Webhooks → Logs to debug issues.