> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trystratos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get notified of events instead of polling GET /v1/jobs/{id}.

<Warning>
  Webhook **registration** is live (`POST /v1/webhooks`). The delivery loop that actually sends events to your URL is not built yet in this release — registering a webhook today stores it but nothing will be delivered to it until a follow-up ships. Poll `GET /v1/jobs/{id}` or `GET /v1/content/{id}` in the meantime. This page documents the intended shape so integrations can be written against it ahead of delivery landing.
</Warning>

## Registering

```bash theme={null}
curl -X POST https://www.try-orbit.com/api/v1/webhooks \
  -H "Authorization: Bearer $STRATOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/webhooks/stratos", "events": ["content.approved", "schedule.sent_to_drafts"]}'
```

Requires the `webhooks:write` scope and an `https://` URL. The response includes a signing secret (`whsec_...`) shown once — store it.

## Events

| Event                                   | Fires when                                             |
| --------------------------------------- | ------------------------------------------------------ |
| `job.completed`                         | An async generation job finishes (ready or failed)     |
| `content.approved` / `content.rejected` | `POST /v1/content/{id}/approve` or `/reject` is called |
| `schedule.sent_to_drafts`               | A schedule with `mode: "draft"` succeeds               |
| `schedule.published`                    | A schedule with `mode: "publish"` succeeds             |
| `schedule.failed`                       | A schedule fails at TikTok's end                       |

## Verifying signatures (once delivery lands)

Each delivery will carry an `X-Stratos-Signature` header — HMAC-SHA256 of the raw request body, hex-encoded, using your webhook's signing secret:

```js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```