Verify webhook signatures
Every request to a webhook endpoint includes the X-Onvo-Signature header. Verify it before processing the event: it confirms that the request comes from ONVO, that the body was not changed, and that it is not an old request replayed by someone else.
X-Onvo-Signature: t=1785758400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
| Part | Description |
|---|---|
t | Unix timestamp, in seconds, of when ONVO sent the attempt. Each attempt gets a new one. |
v1 | HMAC-SHA256 signature in hexadecimal. While a secret is being rotated, the header carries two v1 values: one for each valid secret. |
Algorithm
- Read the raw request body, exactly as it arrived, before converting it to JSON. Any change, even to whitespace, invalidates the signature.
- Split the header on commas and read the
tvalue and everyv1value. - Reject the request if
tis more than 300 seconds away from your server's current time. - Compute the hexadecimal HMAC-SHA256 of the text
t+.+ raw body, using the endpoint's signing secret (whsec_...). - Accept the request if the result matches any of the
v1values. Compare with a constant-time function. - Only then convert the body to JSON and process the event.
Keep the signing secret in an environment variable or a secrets manager, never in code. If your server receives events from several endpoints, use each endpoint's own secret.
Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyOnvoWebhook(rawBody, signatureHeader, secret, now = Date.now()) {
const parts = signatureHeader.split(",").map((part) => part.trim().split("=", 2));
const timestamp = Number(parts.find(([key]) => key === "t")?.[1]);
const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
if (!Number.isSafeInteger(timestamp) || Math.abs(Math.floor(now / 1000) - timestamp) > 300) {
return false;
}
const expected = createHmac("sha256", secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest();
return signatures.some((candidate) => {
if (!/^[0-9a-f]{64}$/i.test(candidate)) return false;
const received = Buffer.from(candidate, "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
});
}
With Express, use express.raw on the webhook route to receive the body as a Buffer, before any JSON parser:
import express from "express";
const app = express();
app.post("/webhooks/onvo", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.get("X-Onvo-Signature") ?? "";
if (!verifyOnvoWebhook(req.body, signature, process.env.ONVO_WEBHOOK_SECRET)) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body.toString("utf8"));
// Store the event by its `event.id` and process it in the background.
res.sendStatus(200);
});
PHP
<?php
function verifyOnvoWebhook(string $rawBody, string $header, string $secret, ?int $now = null): bool {
$timestamp = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
[$key, $value] = array_pad(explode('=', trim($part), 2), 2, null);
if ($key === 't' && ctype_digit((string) $value)) $timestamp = (int) $value;
if ($key === 'v1' && is_string($value)) $signatures[] = $value;
}
$now = $now ?? time();
if ($timestamp === null || abs($now - $timestamp) > 300) return false;
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
foreach ($signatures as $candidate) {
if (preg_match('/^[0-9a-f]{64}$/i', $candidate) && hash_equals($expected, strtolower($candidate))) return true;
}
return false;
}
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ONVO_SIGNATURE'] ?? '';
if (!verifyOnvoWebhook($rawBody, $signature, getenv('ONVO_WEBHOOK_SECRET'))) {
http_response_code(400);
exit;
}
$event = json_decode($rawBody, true);
http_response_code(200);
Python
import hashlib
import hmac
import time
def verify_onvo_webhook(raw_body: bytes, header: str, secret: str, now: int | None = None) -> bool:
pairs = [part.strip().split("=", 1) for part in header.split(",") if "=" in part]
timestamp_values = [value for key, value in pairs if key == "t" and value.isdigit()]
signatures = [value.lower() for key, value in pairs if key == "v1"]
if not timestamp_values:
return False
timestamp = int(timestamp_values[0])
if abs((now or int(time.time())) - timestamp) > 300:
return False
signed = str(timestamp).encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return any(len(candidate) == 64 and hmac.compare_digest(expected, candidate) for candidate in signatures)
In Flask, read the raw body with request.get_data() and the header with request.headers.get("X-Onvo-Signature", "").
Test your verification
Use Test connection on the endpoint's detail page. ONVO sends a webhook_endpoint.test event signed like a delivery, with every valid secret (during a rotation, with both the new and the previous one); if your server responds with 2xx, the test is recorded as successful.
If verification fails:
- Check that you sign the raw body and not re-serialized JSON.
- Confirm that you use this endpoint's secret, in the same mode (test or live).
- Check that your server's clock is synchronized with NTP.