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

# Webhooks

> Cadastre URLs, receba eventos em tempo real e consulte entregas — via API ou painel.

<Tip>
  Webhook é a **campainha do seu servidor**: quando algo muda na Notifique, a API toca com um POST JSON na sua URL.
</Tip>

## O que é?

É uma **URL HTTPS** no seu sistema que recebe avisos automáticos: mensagem enviada, entregue, resposta do cliente, instância desconectada, clique em link curto…

Na Platform API você **cadastra, edita e audita** webhooks com `/v1/webhooks` e `/v1/webhooks/deliveries`.

## Quando usar?

| Situação                               | Webhook?    |
| -------------------------------------- | ----------- |
| Reagir **na hora** quando algo muda    | **Sim**     |
| Automatizar bot, ERP ou agente de IA   | **Sim**     |
| Só consultar o painel de vez em quando | Não precisa |

## Cadastrar via API

Escopos: `webhooks:read` e `webhooks:manage`.

```bash theme={null}
curl -X POST https://api.notifique.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu webhook",
    "url": "https://api.seudominio.com/receive",
    "events": ["message.sent", "message.delivered", "sms.sent"],
    "instanceIds": []
  }'
```

**Guarde o `secret`** da resposta para validar `X-Notifique-Signature`.

## Validar assinatura

Cada POST traz `X-Notifique-Signature` e `X-Notifique-Timestamp`. Calcule HMAC-SHA256 do secret com `{timestamp}.{body bruto}` e rejeite timestamps fora de **5 minutos**.

## Entregas e reenvio

| Método | Rota                                          | Uso                                   |
| ------ | --------------------------------------------- | ------------------------------------- |
| GET    | `/v1/webhooks/deliveries`                     | Histórico de tentativas POST          |
| GET    | `/v1/webhooks/deliveries/{deliveryId}`        | Payload, resposta HTTP e tentativas   |
| POST   | `/v1/webhooks/deliveries/{deliveryId}/resend` | Reenfileirar entrega                  |
| POST   | `/v1/webhooks/{id}/rotate-secret`             | Novo `secret` de assinatura (uma vez) |

Filtros em listagem: `success`, `event`, `webhook_id`, `message_id`, `search`.

## Sandbox x produção

* **Sandbox** (`sk_test_...`): mesmos nomes de evento; payload com `sandbox: true`
* **Produção** (`sk_live_...`): eventos reais

Mais detalhes e lista de eventos por canal: [Webhooks (guia completo)](/guides/webhooks/index).

## Próximos passos

* [Logs da API](/platform-api/como-funciona/logs): auditar chamadas HTTP
* [Escopos](/platform-api/como-funciona/escopos-api-key): permissões na chave