Referência

Webhooks

Receba uma requisição assinada no seu servidor quando uma publicação sai ou falha, um arquivo fica pronto ou uma conta social precisa de atenção.

Adicionar um endpoint

1
No SPREVA, abra Desenvolvimento, depois Webhooks, adicione o endereço do seu servidor e escolha os eventos que ele deve receber. O endereço precisa ser público e responder com um status 2xx em até 10 segundos.
2
Copie o segredo do endpoint. Ele aparece só uma vez, e é com ele que você confere a assinatura de cada requisição.
3
Use Enviar teste. Ele manda um evento webhook.test, assinado como os de verdade, e Entregas recentes mostra o status que seu servidor respondeu e quanto tempo levou.

Você também pode adicionar um endpoint pela API REST, com uma chave que tenha webhooks:write.

O que cada requisição traz

Um POST com um corpo JSON e quatro cabeçalhos:

x-spreva-event: o evento, como target.published.
x-spreva-event-id: o mesmo que o id do corpo, e igual em cada nova tentativa e reenvio.
x-spreva-timestamp: quando a requisição foi assinada, em segundos Unix.
x-spreva-signature: v1= seguido da assinatura.

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 é o próprio evento, e data.type é o nome dele dentro do SPREVA. Use os ids em data para buscar o objeto completo pela API REST.

Eventos

Um endpoint recebe os eventos que escolheu. Enviar teste chega até ele independentemente do que escolheu.

Publicações

post.created: Uma publicação foi criada
post.scheduled: Uma publicação ganhou uma data
post.published: Uma publicação saiu em todas as contas
post.partial: Uma publicação terminou com resultados diferentes entre as contas
post.failed: Uma publicação falhou em todas as contas

Envios (um por conta)

target.published: Uma conta publicou a publicação
target.failed: Uma conta não conseguiu publicar
target.awaiting_user: Uma conta precisa que você termine de publicar no aplicativo dela

Mídia

media.ready: Um arquivo enviado está pronto para usar
media.failed: Um arquivo não pôde ser processado ou gerado

Contas sociais

connection.expired: Uma conta social precisa ser conectada de novo
connection.revoked: Uma conta social retirou a permissão

Análises

analytics.updated: Chegaram números novos de uma publicação já publicada

Conferir a assinatura

A assinatura é um HMAC-SHA256 do timestamp, de um ponto e do corpo bruto, com o segredo do endpoint como chave. Rejeite qualquer requisição cuja assinatura não bata.

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);
}

Confira usando o corpo exatamente como chegou, antes de interpretar o JSON: interpretar e escrever de novo muda os bytes, e a assinatura deixa de bater.

Novas tentativas e reenvios

Responda com um status 2xx em até 10 segundos. Qualquer outra resposta, ou nenhuma, é tentada de novo até 5 vezes: depois de 30 segundos, 2 minutos, 10 minutos, 1 hora e 6 horas.
Redirecionamentos não são seguidos, então use o endereço final do seu endpoint.
Uma nova tentativa ou um reenvio traz o mesmo x-spreva-event-id: use esse id para ignorar um evento que você já tratou.
Reenviar entrega, em Entregas recentes, manda um evento de novo, com as novas tentativas se seu servidor ainda falhar, então você conserta seu endpoint sem publicar duas vezes.