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

# Webhooks

> Notificações assíncronas de eventos, sem necessidade de polling

Notifica eventos assíncronos por HTTP — hoje, conclusão/falha de [triagem de mídia adversa](/concepts/adverse-media). Alternativa a polling em `GET /adverse-media/{uuid}`.

## Catálogo de eventos

| Evento                    | Quando dispara                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `webhook.test`            | Disparado manualmente via `POST .../test`, para verificar que seu endpoint está acessível. |
| `adverse_media.completed` | Uma triagem de mídia adversa foi concluída com sucesso.                                    |
| `adverse_media.failed`    | Uma triagem de mídia adversa falhou.                                                       |

## Gerenciar endpoints de webhook

### `POST /webhooks/endpoints`

Cria um novo endpoint de webhook. **Escopo:** `webhooks:write`.

```json theme={null}
{
  "name": "Callback do meu sistema",
  "url": "https://meusistema.com/webhooks/nllabs",
  "subscribed_events": ["adverse_media.completed", "adverse_media.failed"]
}
```

A resposta inclui o campo `secret` — **o segredo de assinatura em texto puro é retornado apenas nesta chamada**. Guarde-o com segurança; ele é usado para verificar a autenticidade das entregas. Chamadas subsequentes (`GET`) nunca retornam o segredo novamente.

### `GET /webhooks/endpoints`

Lista os endpoints configurados. **Escopo:** `webhooks:read`.

### `GET /webhooks/endpoints/{endpoint_uuid}`

Detalha um endpoint específico, incluindo `status`, `consecutive_failures`, `last_success_at`/`last_failure_at`. **Escopo:** `webhooks:read`.

### `PATCH /webhooks/endpoints/{endpoint_uuid}`

Atualiza `name`, `url`, `subscribed_events` e/ou `status` (todos os campos são opcionais — envie apenas o que quer alterar). **Escopo:** `webhooks:write`.

### `POST /webhooks/endpoints/{endpoint_uuid}/rotate-secret`

Gera um novo segredo de assinatura para o endpoint, invalidando o anterior. Assim como na criação, **o novo segredo em texto puro é retornado apenas nesta chamada**. **Escopo:** `webhooks:write`.

### `POST /webhooks/endpoints/{endpoint_uuid}/test`

Envia um evento `webhook.test` para o endpoint, para verificar que ele está acessível e processando entregas corretamente. **Escopo:** `webhooks:write`.

## Reenviar uma entrega

### `POST /webhooks/webhook-events/{event_uuid}/retry`

Agenda o reenvio de um evento de webhook que falhou (apenas eventos com status `failed` são elegíveis; retentar um evento em outro status retorna `409`). **Escopo:** `webhooks:retry` — um escopo próprio, distinto de `webhooks:read`/`webhooks:write`.