Referência

Webhooks

Receba um pedido assinado no seu servidor quando uma publicação sai ou falha, um ficheiro 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 de que deve ser avisado. O endereço tem de ser público e responder com um estado 2xx em menos de 10 segundos.
2
Copie o segredo do endpoint. Só é mostrado uma vez e é com ele que verifica a assinatura de cada pedido.
3
Use Enviar teste. Envia um evento webhook.test, assinado como os verdadeiros, e Entregas recentes mostra o estado que o seu servidor respondeu e quanto tempo demorou.

Também pode adicionar um endpoint através da API REST, com uma chave que tenha webhooks:write.

O que traz cada pedido

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 repetição e reenvio.
x-spreva-timestamp: quando o pedido foi assinado, 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 obter o objeto completo através da API REST.

Eventos

Um endpoint recebe os eventos que escolheu. Enviar teste chega-lhe seja o que for que tenha escolhido.

Publicações

post.created: Foi criada uma publicação
post.scheduled: Uma publicação recebeu 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 termine a publicação na aplicação dela

Multimédia

media.ready: Um ficheiro carregado está pronto a usar
media.failed: Um ficheiro não pôde ser processado ou gerado

Contas sociais

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

Estatísticas

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

Verificar a assinatura

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

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

Verifique-a com o corpo exatamente como chegou, antes de o interpretar como JSON: interpretá-lo e voltar a escrevê-lo muda os bytes, e a assinatura deixa de corresponder.

Repetições e reenvios

Responda com um estado 2xx em menos de 10 segundos. Qualquer outra resposta, ou nenhuma, é repetida até 5 vezes: ao fim de 30 segundos, 2 minutos, 10 minutos, 1 hora e 6 horas.
Os redirecionamentos não são seguidos, por isso use o endereço final do seu endpoint.
Uma repetição ou um reenvio traz o mesmo x-spreva-event-id: use-o para ignorar um evento que já tratou.
Reenviar entrega, em Entregas recentes, envia um evento outra vez, com as repetições se o seu servidor ainda falhar, para poder corrigir o endpoint sem publicar duas vezes.