Verify a webhook signature
Ten lines, in the language you already use. An unverified webhook is an endpoint anyone on the internet can post to.
Woyra signs every delivery with the endpoint’s secret over the timestamp and the exact body it sent. Recompute it, compare in constant time, and reject anything older than a few minutes so a captured request cannot be replayed at you later.
Woyra-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Woyra-Timestamp: 1764547200
Woyra-Event-Id: evt_01K...
Woyra-Event-Type: email.deliveredThe signature is the hex HMAC-SHA256, keyed with the endpoint’s secret, of the timestamp, a full stop, and the raw body: 1764547200.{"id":"evt_...",...}. It is sent prefixed with v1=, so a future scheme can sit beside it.
import { createHmac, timingSafeEqual } from 'node:crypto';
// headers: the request's headers; rawBody: the body exactly as received (a string or Buffer).
export function verify(headers, rawBody, secret, toleranceSeconds = 300) {
const timestamp = headers['woyra-timestamp'] ?? '';
const signature = String(headers['woyra-signature'] ?? '').replace(/^v1=/, '');
if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) < toleranceSeconds)) return false;
const expected = createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest('hex');
const a = Buffer.from(expected), b = Buffer.from(signature);
return a.length === b.length && timingSafeEqual(a, b);
}import hashlib, hmac, time
def verify(headers, raw_body: bytes, secret: str, tolerance: int = 300) -> bool:
timestamp = headers.get("Woyra-Timestamp", "")
signature = headers.get("Woyra-Signature", "").removeprefix("v1=")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) >= tolerance:
return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)function woyra_verify(string $timestamp, string $signatureHeader, string $rawBody, string $secret, int $tolerance = 300): bool {
// $timestamp = $_SERVER['HTTP_WOYRA_TIMESTAMP']; $signatureHeader = $_SERVER['HTTP_WOYRA_SIGNATURE'];
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) >= $tolerance) return false;
$signature = preg_replace('/^v1=/', '', $signatureHeader);
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($expected, $signature);
}func Verify(h http.Header, body []byte, secret string, tolerance time.Duration) bool {
timestamp := h.Get("Woyra-Timestamp")
ts, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil || time.Since(time.Unix(ts, 0)).Abs() >= tolerance {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(timestamp + "."))
mac.Write(body)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(strings.TrimPrefix(h.Get("Woyra-Signature"), "v1=")))
}def woyra_verify(timestamp, signature_header, raw_body, secret, tolerance = 300)
# timestamp = request.headers["Woyra-Timestamp"]; signature_header = request.headers["Woyra-Signature"]
return false unless timestamp.to_s.match?(/Ad+z/) && (Time.now.to_i - timestamp.to_i).abs < tolerance
expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
OpenSSL.secure_compare(expected, signature_header.to_s.delete_prefix("v1="))
endWhat Woyra does on its side
- Delivery is at-least-once with a retry ladder, so acknowledge fast and do the work afterwards.
- Deduplicate on the event id: a retry carries the same one.
- An endpoint that keeps failing is quarantined and you are told, rather than hammered forever.
- Every attempt, its response and its body are in the console’s webhook debugger, and can be replayed from there.
Questions
Where do I get the signing secret?
It is shown when you register the endpoint, in the console or through the API, and it is derived per endpoint so a leak scopes to one destination.
What should my endpoint return?
Any 2xx, as fast as you can. A slow endpoint is retried and eventually quarantined, so queue the work rather than doing it inline.
Which events exist?
For email: email.sent, email.delivered, email.undelivered (a bounce), email.failed (refused before it left), email.complained, email.canceled (a scheduled email withdrawn), email.opened, email.clicked and email.received. SMS has the message.* equivalents, Verify has verification.*, and voice has call.*. Each endpoint receives every event unless you give it a list of the ones it wants.
Next
Get a test key and run any of this in about ninety seconds.