# Webhooks

Set a URL with `PUT https://wyroapi.com/v1/webhooks {"url": "https://…"}`. The response carries the signing `secret` (shown once). Partners can also set one URL for all their clients in the developer panel.

## Events

| Event | When |
| --- | --- |
| `post.published` | A real post went out on every network. |
| `post.partial` | It went out on some networks and failed on others. |
| `post.failed` | It failed on every network (`error` per network). |
| `account.connected` | A real account was connected. |
| `account.disconnected` | An account was disconnected. |

Each delivery is a `POST` with JSON `{ id, type, created_at, workspace_id, external_id, data }`.

## Headers

| Header | Value |
| --- | --- |
| `X-Wyro-Signature` | Hex HMAC-SHA256 of `${X-Wyro-Timestamp}.${raw body}`, keyed by your secret. |
| `X-Wyro-Timestamp` | Unix seconds of this attempt. Reject it if it is more than 5 minutes old. |
| `X-Wyro-Attempt` | 1 for the first attempt, 2 to 8 for retries. |
| `X-Wyro-Event-Id` | The event's `id` (same as in the body). |

## Delivery contract

- **First attempt** right after the event. Each attempt waits **5 s** at most; only a **2xx** counts as delivered (redirects are not followed).
- **Retries** after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: **8 attempts** over about 45 hours. Then the delivery is marked failed.
- **Same id in every attempt.** Retries can reach you after a success we did not see (e.g. your 2xx timed out): **dedupe on `id`**. Events can arrive out of order; use `created_at` and `GET /v1/posts/{id}` for the current state.
- **Disabling.** If an endpoint keeps failing for **3 days** (no 2xx in between), it is disabled and gets no more events. `GET /v1/webhooks` shows `"status": "disabled"` and `disabled_at` (partners see it in the developer panel). Fix the endpoint and set the URL again (`PUT /v1/webhooks`, or save it in the panel) to turn it back on.

Answer 2xx fast and do the work afterwards (a queue), so slow work does not time out.

## Verify the signature

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

The SDKs include it: `verifySignature(secret, timestamp, body, signature)` ([SDKs](https://wyroapi.com/en/docs/sdks)).
