Safe Creative Platform

7. Webhooks

Configura endpoints en la consola y elige qué recibir: certification.completed / .failed, balance.low, balance.exhausted, events.unpaid_limit_reached, consumption.limit_reached, recharge.auto_completed / .auto_failed. Desde la consola puedes pedir además una entrega de prueba (webhook.test) a cualquier endpoint.

Todas las entregas comparten el mismo sobre JSON: id (igual en los reintentos), type, created_at, mode (live o test: los avisos de saldo y límites son siempre live; los de certificación llevan el modo de la certificación) y data, cuyo modelo depende de type:

type Se envía cuando Campos de data
certification.completed La certificación se ha emitido certification_id, channel_id, status, event_count, verification_code
certification.failed La certificación no se ha podido emitir (se devuelve el cobro) certification_id, channel_id, status, event_count, incident_id
balance.low El saldo baja de un umbral de aviso (una vez por cruce) threshold_id, threshold, balance
balance.exhausted El primer evento entra como impagado channel_id
events.unpaid_limit_reached Se alcanza el límite de impagados: el API rechaza registros con 402 unpaid_limit, unpaid_events, unpaid_credits
consumption.limit_reached Un límite de consumo llega a su tope en el periodo limit_id, scope, channel_id, key_id, period, period_key, max_events, action
recharge.auto_completed Se ha cobrado una recarga automática y sus créditos ya están en el saldo recharge_id, pack_id, credits, amount, currency, threshold, balance
recharge.auto_failed Una recarga automática ha fallado y se ha desactivado recharge_id, pack_id, credits, amount, currency, threshold, reason, payment_url, auto_recharge_disabled
webhook.test Pides una entrega de prueba en la consola endpoint_id, message 
{
  "id": "ntc_…",
  "type": "balance.low",
  "created_at": "2026-09-28T07:00:16.526317Z",
  "mode": "live",
  "data": { "threshold_id": "thr_…", "threshold": 1000, "balance": 999 }
}

Los créditos son enteros y las fechas, UTC con seis decimales. El detalle de cada campo está en la referencia del API (esquemas Webhook…Data). Con el tiempo podemos añadir campos a data: ignora los que no conozcas.

Cada entrega va firmada con el secreto del endpoint y se reintenta con retroceso exponencial hasta 24 horas (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h). El registro de entregas está en la consola; si un endpoint falla de forma sostenida se desactiva y te avisamos por correo.

Cómo verificar una entrega antes de procesarla:

  1. Toma las cabeceras X-SC-Timestamp (segundos Unix) y X-SC-Signature (v1=<hex>).
  2. Calcula HMAC-SHA256 con tu secreto (whsec_…) sobre <X-SC-Timestamp>.<cuerpo tal cual> y compáralo en tiempo constante con <hex>.
  3. Rechaza marcas de tiempo de hace más de 5 minutos.
  4. Responde cualquier 2xx; deduplica por X-SC-Webhook-Id (el id del sobre, igual en los reintentos).
← Certificaciones Precios y saldo →