> ## 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

> Aprenda como receber eventos da Notifique no seu sistema em tempo real.

<Tip>
  Webhook é a **campainha do seu servidor**: quando algo acontece na Notifique (mensagem enviada, entregue, resposta do cliente…), a gente toca a campainha com um POST JSON na sua URL.
</Tip>

## O que é um webhook?

É uma **URL HTTPS** no seu sistema que recebe avisos automáticos da Notifique. Em vez de ficar perguntando "já entregou?" para a API, você **espera o aviso chegar**.

Pense como notificação push, só que para o seu backend.

## Para que serve?

Com webhooks você pode:

* **Saber na hora** quando uma mensagem foi enviada, entregue, lida ou falhou
* **Automatizar** pedidos, CRM, financeiro e bots sem olhar o painel
* **Processar** mensagens que o cliente mandou (WhatsApp, Telegram, SMS)
* **Monitorar** conexão de instâncias (QR, conectado, desconectado)
* **Rastrear** cliques em links curtos e eventos de Forms

## Quando usar?

| Situação                                     | Usar webhook? |
| -------------------------------------------- | ------------- |
| Precisa reagir **na hora** quando algo muda  | **Sim**       |
| Quer automatizar (bot, ERP, sistema próprio) | **Sim**       |
| Só consulta o painel de vez em quando        | Não precisa   |

## Como configurar

### 1. Prepare seu endpoint

Crie uma rota **HTTPS** que aceita **POST** com JSON e responde **2xx** rápido.

Exemplo: `https://meusite.com/webhooks/notifique`

Se o processamento for pesado, **enfileire** do seu lado e responda 200 logo. É como atender a campainha e resolver a visita depois.

### 2. Cadastre no painel

Abra **Developer → Webhooks**, crie um webhook e marque os [eventos](#eventos-por-canal) que importam para você.

Também dá para cadastrar pela API com escopos `webhooks:manage` e `webhooks:read`. Precisa de chave? Veja [Chaves de API](/guides/api-key/index).

```http theme={null}
POST https://api.notifique.dev/v1/webhooks
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "name": "Meu webhook",
  "url": "https://api.seudominio.com/receive",
  "events": ["message.sent", "message.delivered", "sms.sent"],
  "instanceIds": []
}
```

**Guarde o secret** da resposta. Você usa ele para validar cada POST.

### 3. Valide a 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**.

Detalhes na seção [Headers e assinatura](#headers-e-assinatura) abaixo.

### 4. Trate retentativas

Se seu endpoint falhar, tentamos de novo em **5 min, 30 min e 2 h**. Responda **2xx** rápido.

## Sandbox x Produção

* **Sandbox** (`sk_test_...`): mesmos nomes de evento; o payload traz `sandbox: true`
* **Produção** (`sk_live_...`): eventos reais do tráfego

Simule eventos em **Developer → Caixa sandbox**. Mais em [Sandbox, o que é?](/guides/sandbox/index).

## Formato do payload

Todas as requisições são **POST** com `Content-Type: application/json`. O corpo segue a estrutura:

```json theme={null}
{
  "event": "message.sent",
  "workspaceId": "clxx...",
  "instanceId": "clxx...",
  "messageId": "clxx...",
  "timestamp": "2025-02-09T12:00:00.000Z",
  "data": { ... }
}
```

| Campo           | Tipo                | Descrição                                                                                                                    |
| --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **event**       | string              | Nome do evento (ex.: `message.sent`, `sms.delivered`).                                                                       |
| **workspaceId** | string              | ID do workspace.                                                                                                             |
| **instanceId**  | string              | ID da instância WhatsApp (vazio para SMS, e-mail e push).                                                                    |
| **messageId**   | string \| undefined | ID da mensagem no Notifique (quando aplicável); em **`short_link.clicked`** é o **clickEventId** (id do registro de clique). |
| **timestamp**   | string              | ISO 8601; use para anti-replay (janela recomendada: 5 min).                                                                  |
| **data**        | object              | Dados específicos do evento (veja a página de cada canal abaixo).                                                            |

## Headers e assinatura

| Header                    | Descrição                                         |
| ------------------------- | ------------------------------------------------- |
| **Content-Type**          | `application/json`                                |
| **X-Webhook-Event**       | Nome do evento.                                   |
| **X-Notifique-Timestamp** | Timestamp em segundos (Unix) usado na assinatura. |
| **X-Notifique-Signature** | Assinatura: `t={timestamp},v1={hash}`.            |
| **X-Workspace-Id**        | ID do workspace.                                  |

* **Cálculo HMAC:** `hash = HMAC-SHA256(secret, timestamp + "." + body)` (body = corpo bruto do POST).
* **Anti-replay:** Rejeite requisições com timestamp fora de uma janela (ex.: 5 minutos).

## Mensagens recebidas (inbound)

Para processar o que o **cliente mandou** (WhatsApp, Telegram, SMS):

1. Marque o evento no webhook
2. Configure inbound em **Settings → Received messages**

O webhook avisa com um resumo. Para **baixar mídia** (áudio, imagem, documento) no WhatsApp, use o `inboundId` na API. Guia completo: [Mensagens recebidas e respostas](/guides/webhooks/mensagens-recebidas-e-respostas).

## Boas práticas

1. **HTTPS sempre** na URL cadastrada
2. **Responda 2xx rápido** e processe em background
3. **Valide a assinatura** em todo POST
4. **Marque só os eventos** que sua integração consome

Mais detalhes: [Segurança e Confiabilidade](/guides/conceitos/seguranca-e-confiabilidade).

## Eventos por canal

Cada canal tem seus próprios eventos. Marque só o que precisa:

<CardGroup cols={2}>
  <Card title="WhatsApp" icon="whatsapp" href="/whatsapp-api/como-funciona/eventos-do-webhooks">
    Envio, entrega, inbound e instância
  </Card>

  <Card title="SMS" icon="comment-sms" href="/sms-api/como-funciona/eventos-do-webhooks">
    Envio, DLR, MO e respostas
  </Card>

  <Card title="Telegram" icon="paper-plane" href="/telegram-api/como-funciona/eventos-do-webhooks">
    Envio, inbound e instância
  </Card>

  <Card title="Instagram" icon="instagram" href="/instagram-api/como-funciona/eventos-do-webhooks">
    Envio, comentários e inbound
  </Card>

  <Card title="E-mail" icon="envelope" href="/emails-api/como-funciona/eventos-do-webhooks">
    Envio, abertura, clique e bounce
  </Card>

  <Card title="Push" icon="bell" href="/push-api/como-funciona/eventos-do-webhooks">
    Envio, entrega e clique
  </Card>

  <Card title="RCS" icon="mobile-screen" href="/rcs-api/como-funciona/eventos-do-webhooks">
    Envio, entrega e falha
  </Card>

  <Card title="Voz" icon="phone" href="/voice-api/como-funciona/eventos-do-webhooks">
    Chamadas e gravações
  </Card>

  <Card title="Forms" icon="clipboard-list" href="/marketing-addons-api/como-funciona/eventos-do-webhooks">
    Inscrição, confirmação e cancelamento
  </Card>

  <Card title="Links curtos" icon="link" href="/short-links-api/como-funciona/eventos-do-webhooks">
    Cliques e conversões
  </Card>

  <Card title="Números de telefone" icon="hashtag" href="/phone-numbers-api/como-funciona/eventos-do-webhooks">
    Ciclo de vida do número contratado
  </Card>

  <Card title="Automações" icon="bolt" href="/automations-api/como-funciona/eventos-do-webhooks">
    Ativar, pausar e lifecycle de runs
  </Card>

  <Card title="Templates (Meta)" icon="file-lines" href="/template-api/como-funciona/eventos-do-webhooks">
    Aprovação, rejeição e categoria
  </Card>
</CardGroup>

<Note>
  Evento de reputação do workspace (`trust.score_changed`): veja [Trust Factor](/guides/workspaces/trust-factor#webhook-trustscore_changed).
</Note>

***

## Próximos passos

* [Comece aqui](/guides/introducao/comece-aqui): envie sua primeira mensagem
* [Chaves de API](/guides/api-key/index): credenciais para cadastrar webhooks via API