Network operations staffed around the clock
Skyroute
EN · EnglishEN
Talk to salesRequest access
DEVELOPERS / WEBHOOKS

Trust the event you receive.

Skyroute signs each outbound webhook using the secret attached to that endpoint. Verify the raw request before treating a call event as trusted.

OUTBOUND EVENT DELIVERY

Signed request, clear boundary.

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.

EVENT BODY · EXAMPLE
{"event":"call.started","payload":{"id":42,"status":"ringing"}}
SIGNATURE INPUT
HMAC_SHA256(secret, timestamp + "." + raw_body)
02 / VERIFY BEFORE PROCESSING

Keep the raw body intact.

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.

REQUIRED HEADERS
Content-Type: application/json
X-Skyroute-Timestamp: 1793490000
X-Skyroute-Signature: v1=<64 lowercase hex characters>
04 / CURRENT DELIVERY BEHAVIOR

Know the operational limit.

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.