Skyroute signe chaque webhook sortant en utilisant le secret attaché à ce paramètre. Vérifier la demande brute avant de traiter un événement d'appel comme fiable.
Créer un webhook dans les paramètres de compte et stocker son secret de signature lorsque montré. Le secret est chiffré au repos, n'est jamais placé dans la charge utile HTTP, et peut être tourné pour une nouvelle révélation unique.
01 / FORMAT DE LIVRAISON
Les octets qui sont signés.
Skyroute POSTs JSON à l'URL publique HTTPS configurée avec event and payload. X-Skyroute-Timestamp est un horodatage Unix en quelques secondes. X-Skyroute-Signature a le formulaire v1=<lowercase hex>. La signature est HMAC-SHA256 de 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 · EXEMPLE DE VÉRIFICATION
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.
Utilisez les octets exacts reçus. L'analyse et la ré-sérialisation de JSON modifie l'entrée de signature.
03 / ROTATION SECRET
Conservez-le quand il apparaît.
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 renvoie 503 jusqu'à ce qu'un vérificateur de signature spécifique au fournisseur soit configuré.