Signature Verification
Verify webhook signatures to ensure requests are authentic and haven't been tampered with.
Why Verify Signatures?
Webhook signatures protect your application from:
- Spoofed requests: Attackers sending fake webhooks to your endpoint
- Replay attacks: Reusing old webhook payloads
- Tampering: Modified payloads in transit
Signature Headers
Each webhook request includes these headers:
| Header | Description |
|---|---|
x-owl-eyes-signature | HMAC-SHA256 signature of the payload |
x-owl-eyes-timestamp | Unix timestamp when the request was sent |
Verification Algorithm
The signature is computed as follows:
Create the signed payload
Concatenate the timestamp and raw request body with a dot separator:
{timestamp}.{body}Compute HMAC-SHA256
Hash the signed payload using your webhook signing secret.
Compare signatures
Compare the computed signature with the one in the header using a timing-safe comparison.
Verify timestamp
Ensure the timestamp is within an acceptable range (e.g., 5 minutes).
Node.js Implementation
Python Implementation
Go Implementation
PHP Implementation
Common Issues
Body Parsing Issue
Ensure you're using the raw request body, not a parsed JSON object. Body parsing middleware can modify the body before signature verification.
Encoding Mismatch
The body should be treated as UTF-8. Ensure your framework isn't modifying the encoding.
Clock Skew
If timestamp validation fails, check your server's clock. Use NTP to keep it synchronized.
Wrong Secret
Each webhook endpoint has its own secret. Make sure you're using the correct one for the endpoint.