# Webhooks

Crea un endpoint con `POST /v1/webhooks`. La clave necesita el alcance `webhooks`. `url` debe ser HTTPS público. `events` es una lista de nombres del catálogo, o `["*"]` para todos los 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"]
  }'
```

La respuesta incluye `secret` una sola vez. Guárdalo. Las lecturas posteriores del endpoint no lo devuelven. `POST /v1/webhooks/{id}/rotate-secret` emite uno nuevo y el secreto anterior deja de coincidir.

`PATCH` puede poner `status` en `active` o `paused`. `DELETE` detiene las entregas.

## Eventos

| Evento | Cuándo se envía |
| --- | --- |
| `video.viewed` | Una vez por sesión, cuando un espectador empieza a ver |
| `video.progress` | En cada hito del 10% de esa sesión |
| `video.completed` | Cuando un espectador llega al final |
| `conversion.fired` | Cuando un espectador pulsa una llamada a la acción. El cuerpo trae el botón, no un importe |
| `showcase.lead_created` | Cuando un espectador envía por primera vez el formulario de un showcase |
| `video.uploaded` | Cuando un vídeo termina de procesarse y está listo |
| `team.invited` | Cuando se crea una invitación al espacio |
| `experiment.created` | Cuando se crea un borrador de test A/B |
| `experiment.launched` | Cuando un test A/B empieza a recibir tráfico |
| `experiment.promoted` | Cuando una variante pasa a producción |

`GET /v1/webhooks/events` devuelve este catálogo. `POST /v1/webhooks/{id}/test` entrega un evento de ejemplo para que construyas el receptor antes.

## Entrega

AtomicPlayer envía `POST` con un cuerpo JSON.

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

Responde con un estado `2xx`. Una entrega fallida se reintenta a los 1 minuto, 1 hora, 6 horas y 12 horas. Guarda `id` si necesitas ignorar una repetición.

## Verifica la firma

Cada entrega incluye `X-AtomicPlayer-Signature`.

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

`t` es una marca de tiempo Unix en segundos. `v1` es el HMAC-SHA256 en hexadecimal de `${t}.${rawBody}`, firmado con el secreto del endpoint. Usa el cuerpo crudo, no un objeto vuelto a serializar. Compara el hexadecimal en tiempo constante y rechaza una marca de más de 5 minutos respecto a ahora.
