# 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

```js
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](https://wyroapi.com/docs/sdks)).
