wyro

Webhooks

Defina uma URL com PUT https://wyroapi.com/v1/webhooks {"url": "https://…"}. A resposta traz o secret de assinatura (mostrado uma vez). Parceiros também podem definir uma URL para todos os clientes no painel de desenvolvedor.

Eventos

Evento Quando
post.published Um post real saiu em todas as redes.
post.partial Saiu em algumas redes e falhou em outras.
post.failed Falhou em todas as redes (error por rede).
account.connected Uma conta real foi conectada.
account.disconnected Uma conta foi desconectada.

Cada entrega é um POST com JSON { id, type, created_at, workspace_id, external_id, data }.

Headers

Header Valor
X-Wyro-Signature HMAC-SHA256 em hex de ${X-Wyro-Timestamp}.${body cru}, com o seu secret.
X-Wyro-Timestamp Segundos unix desta tentativa. Recuse se tiver mais de 5 minutos.
X-Wyro-Attempt 1 na primeira tentativa, de 2 a 8 nas novas tentativas.
X-Wyro-Event-Id O id do evento (o mesmo do body).

Contrato de entrega

  • Primeira tentativa logo depois do evento. Cada tentativa espera no máximo 5 s; só um 2xx conta como entregue (redirecionamentos não são seguidos).
  • Novas tentativas depois de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: 8 tentativas em cerca de 45 horas. Depois, a entrega fica como falhada.
  • O mesmo id em todas as tentativas. Uma nova tentativa pode chegar depois de um sucesso que não vimos (por exemplo, seu 2xx passou do tempo): deduplique pelo id. Os eventos podem chegar fora de ordem; use created_at e GET /v1/posts/{id} para o estado atual.
  • Desativação. Se um endpoint continuar falhando por 3 dias (sem nenhum 2xx no meio), ele é desativado e não recebe mais eventos. GET /v1/webhooks mostra "status": "disabled" e disabled_at (parceiros veem no painel de desenvolvedor). Corrija o endpoint e defina a URL de novo (PUT /v1/webhooks, ou salve no painel) para reativar.

Responda 2xx rápido e faça o trabalho depois (uma fila), para que um processamento lento não passe do tempo.

Verificar a assinatura

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

// raw = the request body exactly as received (not re-serialized)
function verify(secret, timestamp, raw, signature) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${raw}`).digest("hex");
  return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Os SDKs já trazem isso: verifySignature(secret, timestamp, body, signature) (SDKs).