WoyraDocs
Get an API key

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.

About 4 minutes · Every example runs against a test key, which costs nothing.

The complete guide, end to end · 2 minutes 44 seconds, with narration and English captions.

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.

The headers
Woyra-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Woyra-Timestamp: 1764547200
Woyra-Event-Id: evt_01K...
Woyra-Event-Type: email.delivered

The 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.

Node.js
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);
}
Python
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)
PHP
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);
}
Go
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=")))
}
Ruby
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="))
end
Sign the bytes you receivedVerify the raw request body, before any JSON parsing and re-serialising. A framework that reorders keys or changes whitespace will break a signature that is otherwise perfectly correct.

What Woyra does on its side

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.