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 anX-Monk-Signature header with this format:
The signature is computed over:
Verification Steps
- Extract
t(timestamp) andv1(signature) from the header - Check that the timestamp is within your tolerance window (e.g., 5 minutes)
- Compute the expected signature:
HMAC-SHA256(secret, "{t}.{payload}") - Compare signatures using constant-time comparison
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
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
TheX-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:- Start your local server
- Create a tunnel:
ngrok http 3000 - Add the tunnel URL as a webhook endpoint in Monk
- Trigger events in your Monk sandbox