Retries and idempotency
Every request carries an event_id — the same value on every attempt of the same event. If a delivery fails (a network error, or the receiver returning a non-2XX status), ownr retries it; after the 3rd failed attempt it stops retrying. Use event_id to deduplicate on your side, in case a retry arrives after your first attempt already succeeded but the response was lost.
Verifying webhook signatures
Recompute the HMAC over the exact bytes of the request body received, using the t value from the X-Ownr-Signature header, and compare it against every v1 value present with a constant-time comparison. During the 24 hours after a secret rotation the header carries two v1 values — check the request against both.
PHP
<?php
/**
* Verifies the `X-Ownr-Signature` header ownr sends with every webhook request.
* Pass one secret normally, or your current and previous signing secret during
* the 24-hour window after a rotation — the header carries a `v1` value for each.
*/
function verifyOwnrWebhookSignature(string $body, string $signatureHeader, array $secrets, int $toleranceSeconds = 300): bool {
if (!preg_match('/^t=(\d+),(v1=[a-f0-9]{64}(?:,v1=[a-f0-9]{64})*)$/', $signatureHeader, $matches)) {
return false;
}
$timestamp = (int)$matches[1];
if (abs(time() - $timestamp) > $toleranceSeconds) {
return false;
}
preg_match_all('/v1=([a-f0-9]{64})/', $matches[2], $signatureMatches);
$signatures = $signatureMatches[1];
foreach ($secrets as $secret) {
$expected = hash_hmac('sha256', "{$timestamp}.{$body}", $secret);
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
}
return false;
}
// Example usage in a webhook receiver:
$body = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_OWNR_SIGNATURE'] ?? '';
$isValid = verifyOwnrWebhookSignature($body, $signatureHeader, ['whsec_your_current_secret', 'whsec_your_previous_secret']);
Node.js
const crypto = require('crypto');
/**
* Verifies the `X-Ownr-Signature` header ownr sends with every webhook request.
* Pass one secret normally, or your current and previous signing secret during
* the 24-hour window after a rotation — the header carries a `v1` value for each.
*/
function verifyOwnrWebhookSignature(body, signatureHeader, secrets, toleranceSeconds = 300) {
const match = signatureHeader.match(/^t=(\d+),(v1=[a-f0-9]{64}(?:,v1=[a-f0-9]{64})*)$/);
if (!match) {
return false;
}
const timestamp = parseInt(match[1], 10);
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
return false;
}
const signatures = [...match[2].matchAll(/v1=([a-f0-9]{64})/g)].map((m) => m[1]);
for (const secret of secrets) {
const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
for (const signature of signatures) {
if (crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
return true;
}
}
}
return false;
}
module.exports = { verifyOwnrWebhookSignature };