Webhook Signatures
Every webhook request includes a signature that you should verify to ensure the request came from JetEmail and hasn’t been tampered with.
Each webhook request includes these headers:
| Header | Description |
|---|
X-Webhook-ID | Unique identifier for this event |
X-Webhook-Timestamp | Unix timestamp when the event was sent |
X-Webhook-Signature | HMAC-SHA256 signature (format: sha256=...) |
Verifying Signatures
The signature is computed using HMAC-SHA256 with your webhook secret and the raw request body.
Node.js
Python
PHP
Go
Ruby
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = req.body;
if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(payload);
// Process the event...
res.status(200).send('OK');
});
import hmac
import hashlib
def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = 'sha256=' + hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
# Flask example
from flask import Flask, request
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Webhook-Signature')
payload = request.get_data()
if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
return 'Invalid signature', 401
event = request.get_json()
# Process the event...
return 'OK', 200
<?php
function verifyWebhookSignature($payload, $signature, $secret) {
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
return hash_equals($expected, $signature);
}
// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = getenv('WEBHOOK_SECRET');
if (!verifyWebhookSignature($payload, $signature, $secret)) {
http_response_code(401);
exit('Invalid signature');
}
$event = json_decode($payload, true);
// Process the event...
http_response_code(200);
echo 'OK';
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"io"
"net/http"
)
func verifyWebhookSignature(payload []byte, signature, secret string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(payload)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signature))
}
func webhookHandler(w http.ResponseWriter, r *http.Request) {
signature := r.Header.Get("X-Webhook-Signature")
payload, _ := io.ReadAll(r.Body)
if !verifyWebhookSignature(payload, signature, webhookSecret) {
http.Error(w, "Invalid signature", http.StatusUnauthorized)
return
}
// Process the event...
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
}
require 'openssl'
def verify_webhook_signature(payload, signature, secret)
expected = 'sha256=' + OpenSSL::HMAC.hexdigest('sha256', secret, payload)
Rack::Utils.secure_compare(expected, signature)
end
# Sinatra example
post '/webhook' do
payload = request.body.read
signature = request.env['HTTP_X_WEBHOOK_SIGNATURE']
unless verify_webhook_signature(payload, signature, ENV['WEBHOOK_SECRET'])
halt 401, 'Invalid signature'
end
event = JSON.parse(payload)
# Process the event...
status 200
'OK'
end
Security Best Practices
Always Verify Signatures
Never process webhook events without verifying the signature first. This prevents attackers from sending fake events to your endpoint.
Use HTTPS
Always use HTTPS for your webhook endpoint to ensure the payload is encrypted in transit.
Use Timing-Safe Comparison
Use constant-time string comparison functions to prevent timing attacks when verifying signatures.
Handle Duplicate Events
Use the X-Webhook-ID header to detect and handle duplicate events. Store processed event IDs and skip duplicates.
Replay Prevention
To prevent replay attacks, you can verify that the timestamp is recent:
function isValidTimestamp(timestamp, toleranceSeconds = 300) {
const now = Math.floor(Date.now() / 1000);
const diff = Math.abs(now - timestamp);
return diff <= toleranceSeconds;
}
// Usage
const timestamp = parseInt(req.headers['x-webhook-timestamp']);
if (!isValidTimestamp(timestamp)) {
return res.status(401).send('Request too old');
}
A tolerance of 5 minutes (300 seconds) is recommended to account for clock drift between servers.
Rotating Secrets
If you need to rotate your webhook secret:
- Generate a new secret in Dashboard → Webhooks
- Update your application to accept both the old and new secrets
- Once all events are using the new secret, remove the old one from your code
