# Webhooks

Crie um endpoint com `POST /v1/webhooks`. A chave precisa do escopo `webhooks`. `url` deve ser HTTPS público. `events` é uma lista de nomes do catálogo, ou `["*"]` para todos os eventos.

```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"]
  }'
```

A resposta inclui `secret` uma única vez. Guarde. As leituras seguintes do endpoint não devolvem o segredo. `POST /v1/webhooks/{id}/rotate-secret` emite um novo e o segredo anterior deixa de coincidir.

`PATCH` pode definir `status` como `active` ou `paused`. `DELETE` interrompe as entregas.

## Eventos

| Evento | Quando é enviado |
| --- | --- |
| `video.viewed` | Uma vez por sessão, quando um espectador começa a assistir |
| `video.progress` | Em cada marco de 10% dessa sessão |
| `video.completed` | Quando um espectador chega ao fim |
| `conversion.fired` | Quando um espectador clica numa chamada para ação. O corpo traz o botão, não um valor de pagamento |
| `showcase.lead_created` | Quando um espectador envia pela primeira vez o formulário de lead de um showcase |
| `video.uploaded` | Quando um vídeo termina o processamento e fica pronto |
| `team.invited` | Quando um convite do workspace é criado |
| `experiment.created` | Quando um rascunho de teste A/B é criado |
| `experiment.launched` | Quando um teste A/B começa a receber tráfego |
| `experiment.promoted` | Quando uma variante é promovida para o ar |

`GET /v1/webhooks/events` devolve este catálogo. `POST /v1/webhooks/{id}/test` entrega um evento de exemplo para você construir o receptor antes.

## Entrega

A AtomicPlayer envia `POST` com um corpo JSON.

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

Responda com um status `2xx`. Uma entrega que falha é tentada de novo depois de 1 minuto, 1 hora, 6 horas e 12 horas. Guarde `id` se precisar ignorar uma repetição.

## Verifique a assinatura

Toda entrega inclui `X-AtomicPlayer-Signature`.

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

`t` é um timestamp Unix em segundos. `v1` é o HMAC-SHA256 em hexadecimal de `${t}.${rawBody}`, assinado com o segredo do endpoint. Use o corpo cru, não um objeto serializado de novo. Compare o hexadecimal em tempo constante e recuse um timestamp a mais de 5 minutos de agora.
