Create a webhook in account settings and store its signing secret when shown. The secret is encrypted at rest, is never placed in the HTTP payload, and can be rotated for a new one-time reveal.
01 / DELIVERY FORMAT
The bytes that are signed.
Skyroute POSTs JSON to the configured public HTTPS URL with event and payload. X-Skyroute-Timestamp is a Unix timestamp in seconds. X-Skyroute-Signature has the form v1=<lowercase hex>. The signature is HMAC-SHA256 of timestamp + "." + raw JSON body.
Read the request bytes before JSON parsing. Reject timestamps outside a short tolerance, compute the HMAC with your endpoint secret, and compare the supplied digest in constant time. The example uses a five-minute tolerance; store event IDs or an equivalent deduplication key if your receiver needs replay protection.
NODE.JS · VERIFICATION EXAMPLE
import { createHmac, timingSafeEqual } from 'node:crypto';
function verifySkyroute(rawBody, timestamp, signature, secret) {
if (!/^\d+$/.test(timestamp ?? '')) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const supplied = signature?.startsWith('v1=') ? signature.slice(3) : '';
if (!/^[a-f0-9]{64}$/.test(supplied)) return false;
const expected = createHmac('sha256', secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest();
return timingSafeEqual(expected, Buffer.from(supplied, 'hex'));
}
// In Express, use express.raw({ type: 'application/json' })
// on this route, then pass req.body to verifySkyroute.
// Parse JSON only after verification succeeds.
Use the exact bytes received. Parsing and re-serializing JSON changes the signature input.
03 / SECRET ROTATION
Store it when it appears.
The signing secret appears once after you create or rotate a webhook. Update your receiver immediately when you rotate; the old secret stops signing new deliveries. Existing webhooks whose secret was not saved can be rotated in Webhook Settings.
Most events make one outbound HTTPS attempt per matching active webhook, with a five-second timeout and redirects disabled; failed attempts are logged without automatic retry. Sandbox route_test.result events are an exception: they use a durable retry queue and may arrive more than once. Deduplicate those events using the stable X-Skyroute-Event-Id header or payload.delivery_id. The separate inbound endpoint POST /api/webhooks/events returns 503 until a provider-specific signature verifier is configured.