wyro

Webhooks

Configura una URL con PUT https://wyroapi.com/v1/webhooks {"url": "https://…"}. La respuesta trae el secret de firma (se muestra una vez). Los partners también pueden poner una URL para todos sus clientes en el panel de desarrolladores.

Eventos

Evento Cuándo
post.published Un post real salió en todas las redes.
post.partial Salió en algunas redes y falló en otras.
post.failed Falló en todas las redes (error por red).
account.connected Se conectó una cuenta real.
account.disconnected Se desconectó una cuenta.

Cada entrega es un POST con JSON { id, type, created_at, workspace_id, external_id, data }.

Headers

Header Valor
X-Wyro-Signature HMAC-SHA256 en hex de ${X-Wyro-Timestamp}.${body crudo}, con tu secret.
X-Wyro-Timestamp Segundos unix de este intento. Recházalo si tiene más de 5 minutos.
X-Wyro-Attempt 1 en el primer intento, de 2 a 8 en los reintentos.
X-Wyro-Event-Id El id del evento (el mismo del body).

Contrato de entrega

  • Primer intento apenas ocurre el evento. Cada intento espera 5 s como máximo; solo un 2xx cuenta como entregado (no seguimos redirecciones).
  • Reintentos después de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: 8 intentos en unas 45 horas. Después, la entrega queda como fallida.
  • El mismo id en todos los intentos. Un reintento puede llegarte después de un éxito que no vimos (por ejemplo, tu 2xx tardó demasiado): deduplica por id. Los eventos pueden llegar desordenados; usa created_at y GET /v1/posts/{id} para el estado actual.
  • Desactivación. Si un endpoint sigue fallando durante 3 días (sin ningún 2xx en el medio), se desactiva y no recibe más eventos. GET /v1/webhooks muestra "status": "disabled" y disabled_at (los partners lo ven en el panel de desarrolladores). Arregla el endpoint y vuelve a configurar la URL (PUT /v1/webhooks, o guárdala en el panel) para reactivarlo.

Responde 2xx rápido y haz el trabajo después (una cola), así un proceso lento no se pasa del tiempo.

Verificar la firma

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

Los SDKs ya lo traen: verifySignature(secret, timestamp, body, signature) (SDKs).