Skip to main content

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
PartDescription
tUnix timestamp, in seconds, of when ONVO sent the attempt. Each attempt gets a new one.
v1HMAC-SHA256 signature in hexadecimal. While a secret is being rotated, the header carries two v1 values: one for each valid secret.

Algorithm​

  1. Read the raw request body, exactly as it arrived, before converting it to JSON. Any change, even to whitespace, invalidates the signature.
  2. Split the header on commas and read the t value and every v1 value.
  3. Reject the request if t is more than 300 seconds away from your server's current time.
  4. Compute the hexadecimal HMAC-SHA256 of the text t + . + raw body, using the endpoint's signing secret (whsec_...).
  5. Accept the request if the result matches any of the v1 values. Compare with a constant-time function.
  6. 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.