# Webhooks

Create an endpoint with `POST /v1/webhooks`. The key needs the `webhooks` scope. `url` must be public HTTPS. `events` is a list of names from the catalog, or `["*"]` for every event.

```bash
curl -X POST "https://api.atomicplayer.ai/v1/webhooks" \
  -H "Authorization: Bearer $ATOMICPLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$WORKSPACE_ID"'",
    "name": "CRM",
    "url": "https://example.com/atomicplayer",
    "events": ["video.viewed", "video.completed", "conversion.fired"]
  }'
```

The response includes `secret` once. Store it. Later reads of the endpoint do not return it. `POST /v1/webhooks/{id}/rotate-secret` issues a new one and the previous secret stops matching.

`PATCH` can set `status` to `active` or `paused`. `DELETE` stops deliveries.

## Events

| Event | When it is sent |
| --- | --- |
| `video.viewed` | Once per playback session, when a viewer starts watching |
| `video.progress` | At each 10% milestone in that session |
| `video.completed` | When a viewer reaches the end |
| `conversion.fired` | When a viewer clicks a call to action. The payload has the button, not a payment amount |
| `showcase.lead_created` | When a viewer submits a showcase lead form for the first time |
| `video.uploaded` | When a video finishes processing and is ready to play |
| `team.invited` | When a workspace invitation is created |
| `experiment.created` | When a draft A/B test is created |
| `experiment.launched` | When an A/B test starts serving traffic |
| `experiment.promoted` | When a variant is promoted to live |

`GET /v1/webhooks/events` returns this catalog. `POST /v1/webhooks/{id}/test` delivers one sample event so you can build the receiver first.

## Delivery

AtomicPlayer sends `POST` with a JSON body.

```json
{
  "id": "evt_123",
  "type": "video.viewed",
  "createdAt": "2026-08-02T12:00:00.000Z",
  "workspaceId": "ddaf7e61-1a65-4d59-9f94-d706fc53131a",
  "data": { "videoId": "…", "sessionId": "…" }
}
```

Respond with a `2xx` status. A failed delivery is retried after 1 minute, 1 hour, 6 hours, and 12 hours. Store `id` if you need to ignore a repeat.

## Verify the signature

Every delivery includes `X-AtomicPlayer-Signature`.

```
t=1725000000,v1=hex
```

`t` is a Unix timestamp in seconds. `v1` is the hex HMAC-SHA256 of `${t}.${rawBody}`, signed with the endpoint secret. Use the raw request body, not a re-serialized object. Compare the hex in constant time, and reject a timestamp more than 5 minutes away from now.
