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; usecreated_ateGET /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/webhooksmostra"status": "disabled"edisabled_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).