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; usacreated_atyGET /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/webhooksmuestra"status": "disabled"ydisabled_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).