Network operations staffed around the clock
Skyroute
EN · EnglishEN
Hablar con ventasRequest access
DEVELOPERS / WEBHOOKS

Confía en el evento que recibes.

Skyroute firma cada webhook con el secreto adjunto a ese punto final. Verifique la solicitud cruda antes de tratar un evento de llamada como confiable.

DEL VENTO EVENTO

Solicitud firmada, límite claro.

Crear un webhook en la configuración de la cuenta y guardar su secreto de firma cuando se muestra. El secreto está encriptado en reposo, nunca se coloca en la carga útil HTTP, y puede ser rotado para una nueva revelación de una sola vez.

01 / FORMAT DE LA DECISIÓN

Los bytes que están firmados.

Skyroute POSTs JSON a la URL HTTPS pública configurada event and payload. X-Skyroute-Timestamp es un Timetamp Unix en segundos. X-Skyroute-Signature tiene la forma v1=<lowercase hex>. La firma es HMAC-SHA256 de timestamp + "." + raw JSON body.

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

Mantenga intacto el cuerpo crudo.

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 · EJEMPLO DE VERIFICACIÓN
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 los bytes exactos recibidos. Parsing and re-serializing JSON changes the signature input.

03 / SECRET ROTATION

Guárdalo cuando aparezca.

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.

CUESTIONES NECESARIAS
Content-Type: application/json
X-Skyroute-Timestamp: 1793490000
X-Skyroute-Signature: v1=<64 lowercase hex characters>
04 / BEHAVIOR DE LA DECISIÓN

Conoce el límite operativo.

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 devuelve 503 hasta que se configura un verificador de firma específico del proveedor.