# 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

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

Os SDKs já trazem isso: `verifySignature(secret, timestamp, body, signature)` ([SDKs](https://wyroapi.com/pt/docs/sdks)).
