Referencia

Webhooks

Recibe una petición firmada en tu propio servidor cuando una publicación sale o falla, un archivo está listo o una cuenta social necesita atención.

Añadir un endpoint

1
En SPREVA, abre Desarrollo y luego Webhooks, añade la dirección de tu servidor y elige los eventos que debe recibir. La dirección tiene que ser pública y responder con un estado 2xx en menos de 10 segundos.
2
Copia el secreto del endpoint. Se muestra una sola vez, y es con él con lo que compruebas la firma de cada petición.
3
Usa Enviar prueba. Manda un evento webhook.test, firmado como los de verdad, y Entregas recientes muestra el estado que respondió tu servidor y cuánto tardó.

También puedes añadir un endpoint con la API REST, con una clave que tenga webhooks:write.

Qué lleva cada petición

Un POST con un cuerpo JSON y cuatro cabeceras:

x-spreva-event: el evento, como target.published.
x-spreva-event-id: el mismo que el id del cuerpo, e igual en cada reintento y reenvío.
x-spreva-timestamp: cuándo se firmó la petición, en segundos Unix.
x-spreva-signature: v1= seguido de la firma.

JSON

{
  "id": "7f3c2d10-0000-4000-8000-000000000000",
  "type": "target.published",
  "createdAt": "2026-10-01T09:00:02.412Z",
  "workspaceId": "0b9f6c1e-0000-4000-8000-000000000001",
  "data": {
    "type": "TargetPublished",
    "workspaceId": "0b9f6c1e-0000-4000-8000-000000000001",
    "postId": "5d2a7c3e-0000-4000-8000-000000000002",
    "targetId": "9a1f4b7d-0000-4000-8000-000000000003",
    "provider": "instagram",
    "remoteId": "17900000000000000",
    "remoteUrl": "https://www.instagram.com/p/EXAMPLE/"
  }
}

data es el propio evento, y data.type es su nombre dentro de SPREVA. Usa los ids de data para obtener el objeto completo con la API REST.

Eventos

Un endpoint recibe los eventos que eligió. Enviar prueba le llega elija lo que elija.

Publicaciones

post.created: Se creó una publicación
post.scheduled: Se le puso fecha a una publicación
post.published: Una publicación salió en todas las cuentas
post.partial: Una publicación terminó con resultados distintos según la cuenta
post.failed: Una publicación falló en todas las cuentas

Envíos (uno por cuenta)

target.published: Una cuenta publicó la publicación
target.failed: Una cuenta no pudo publicar
target.awaiting_user: Una cuenta necesita que termines de publicar en su propia aplicación

Multimedia

media.ready: Un archivo subido está listo para usarse
media.failed: Un archivo no se pudo procesar o generar

Cuentas sociales

connection.expired: Una cuenta social necesita volver a conectarse
connection.revoked: Una cuenta social retiró su permiso

Analíticas

analytics.updated: Llegaron números nuevos de una publicación publicada

Comprobar la firma

La firma es un HMAC-SHA256 del timestamp, un punto y el cuerpo en bruto, con el secreto del endpoint como clave. Rechaza cualquier petición cuya firma no coincida.

JavaScript

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

// rawBody: the request body as a string, before any JSON parsing
export function isFromSpreva(rawBody, headers, secret) {
  const signed = headers["x-spreva-timestamp"] + "." + rawBody;
  const expected = Buffer.from("v1=" + createHmac("sha256", secret).update(signed).digest("hex"));
  const received = Buffer.from(headers["x-spreva-signature"] ?? "");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Compruébala con el cuerpo tal cual llegó, antes de interpretarlo como JSON: interpretarlo y volver a escribirlo cambia los bytes, y la firma deja de coincidir.

Reintentos y reenvíos

Responde con un estado 2xx en menos de 10 segundos. Cualquier otra respuesta, o ninguna, se reintenta hasta 5 veces: a los 30 segundos, 2 minutos, 10 minutos, 1 hora y 6 horas.
Las redirecciones no se siguen, así que usa la dirección final de tu endpoint.
Un reintento o un reenvío lleva el mismo x-spreva-event-id: úsalo para ignorar un evento que ya trataste.
Reenviar entrega, en Entregas recientes, manda un evento otra vez, con sus reintentos si tu servidor sigue fallando, así que puedes arreglar tu endpoint sin publicar dos veces.