AiVideoEditor
Empieza gratis
Menú

Revisada el 2026-11-11 · Versión de API 2026-11-09 · Leer Markdown

Webhooks de cliente

Entrega de eventos salientes para tu espacio de trabajo. Registra un endpoint HTTPS, verifica el secreto de firma de un solo uso, y recibe eventos firmados con reintentos acotados.

Registrar un endpoint

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • El secreto de firma (whsec_…) se devuelve una vez: en la primera respuesta de creación exitosa. Guárdalo; una repetición idempotente de la misma creación devuelve el endpoint sin el secreto, y no puede mostrarse de nuevo.
  • Los destinos deben ser HTTPS, resolubles públicamente y estar libres de credenciales incrustadas. Las solicitudes a direcciones privadas, de loopback, link-local (incluidas las de metadatos de nube), unique-local y multicast se rechazan antes de establecer cualquier conexión, y las redirecciones nunca se siguen.
  • El registro encola un evento webhook.verification dirigido a ese endpoint, independiente de su filtro eventTypes. Los eventos ordinarios fluyen solo después de que tu endpoint responda a la verificación con 2xx.

Verificación de las entregas

Cada solicitud incluye:

CabeceraSignificado
x-publisher-event-idID de evento estable: idéntico entre reintentos y repeticiones
x-publisher-event-typeTipo de evento, p. ej. post.published
x-publisher-timestampSegundos Unix
x-publisher-signaturet=<ts>,v1=<hex>

La firma es HMAC-SHA256 sobre ${t}.${event_id}.${raw_body} usando tu secreto de firma. Verifica con una tolerancia de ±300 segundos y rechaza las repeticiones fuera de ella. Ejemplo en Node:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Verifica siempre contra el cuerpo de la solicitud sin procesar antes de analizarlo.

Sobre del evento

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

Catálogo inicial de eventos (extensible; filtros eventTypes en el registro):

  • webhook.verification: carga de desafío; responde 2xx para activar el endpoint
  • post.published: un destino confirmado con un recibo nativo
  • delivery.failed: un destino falló de forma terminal
  • delivery.requires_action: se requiere consentimiento/reconexión/revisión tardía

Los resultados agregados de publicaciones (post.partially_published, post.failed) aún no se emiten; se documentan aquí solo cuando exista un productor, así que no dependas de ellos. Suscríbete a los eventos por destino anteriores y deriva el estado del lote a partir de los resultados de entrega de la publicación.

Reintentos, repetición y desactivación

  • Intentos: inmediatamente, luego +1m, +5m, +30m, +2h, +8h. Los reintentos reutilizan el mismo ID de evento y un cuerpo idéntico byte a byte para que puedas deduplicar con seguridad.
  • 2xx = entregado. 429/5xx/timeouts se reintentan. Los otros 4xx fallan permanentemente para ese evento (corrige el endpoint y luego repite).
  • 410 Gone desactiva el endpoint: no se encolan más eventos hacia él.
  • La repetición autorizada por el operador a través del servicio interno de webhooks reenvía un evento con su ID original. Un intento en vuelo con arrendamiento activo nunca se interrumpe; la repetición informa que el evento está ocupado y puede reintentarse en breve.

Notas operativas

  • Los diagnósticos de entrega almacenan solo códigos de resultado seguros: nunca tu secreto, firmas, cabeceras de solicitud ni cuerpos de respuesta. Las cargas se sanean además: los secretos de proveedor/OAuth y las URLs de presignación de medios se eliminan antes de que algo se encole.
  • Los endpoints tienen alcance de espacio de trabajo: poseer un UUID de endpoint de otro espacio de trabajo no sirve de nada.
  • La entrega es al menos una vez por ocurrencia de evento aceptada; deduplica con x-publisher-event-id.

Disponibilidad de las herramientas de desarrollador

La página Developers lista las claves de API del espacio de trabajo y los endpoints de webhook de forma independiente de la configuración de cifrado del secreto de firma. Crear un webhook requiere una configuración de cifrado del servidor válida; pide al operador del despliegue que resuelva una advertencia de configuración. La gestión de claves de API sigue disponible. Los secretos de firma existentes nunca se vuelven a mostrar.