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.verificationdirigido a ese endpoint, independiente de su filtroeventTypes. 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:
| Cabecera | Significado |
|---|---|
x-publisher-event-id | ID de evento estable: idéntico entre reintentos y repeticiones |
x-publisher-event-type | Tipo de evento, p. ej. post.published |
x-publisher-timestamp | Segundos Unix |
x-publisher-signature | t=<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 endpointpost.published: un destino confirmado con un recibo nativodelivery.failed: un destino falló de forma terminaldelivery.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.