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

# Introdução

> Receba eventos em tempo real do Hub Message no seu sistema via webhooks

export const projectName = 'Hub Message';

## O que são webhooks?

Webhooks são notificações HTTP que o {projectName} envia ao seu servidor quando eventos acontecem em um canal — como uma mensagem recebida, status de entrega, ou mudança de conexão.

Em vez de o seu sistema consultar a API periodicamente (polling), o {projectName} **envia os eventos para você** assim que acontecem.

```
Cliente envia mensagem → Hub Message → POST para sua URL → Seu sistema processa
```

<Note>
  Webhooks exigem a role **ENTERPRISE** na sua conta. Se sua conta não tem essa role, as chamadas de CRUD de webhook retornam `422`. Entre em contato com o suporte para habilitar.
</Note>

## Eventos disponíveis

| Evento                  | Quando é disparado                                        |
| ----------------------- | --------------------------------------------------------- |
| `MESSAGE_RECEIVED`      | Uma mensagem foi recebida no canal                        |
| `MESSAGE_DELIVERY`      | Confirmação de entrega de uma mensagem enviada            |
| `MESSAGE_STATUS`        | Atualização de status de uma mensagem (lida, falha, etc.) |
| `RECEIVED_STATUS`       | Combinação de recebimento e status                        |
| `RECEIVED_AND_DELIVERY` | Combinação de recebimento e entrega                       |
| `CONNECTED`             | O canal foi conectado                                     |
| `DISCONNECTED`          | O canal foi desconectado                                  |
| `PRESENCE_CHAT`         | Indicador de presença ou digitação de um contato          |
| `INITIAL_DATA`          | Sincronização inicial de dados ao conectar o canal        |
| `BLOCK`                 | Evento de bloqueio de contato                             |

## Formatos de payload

O {projectName} suporta três formatos de payload:

| Formato   | Descrição                     |
| --------- | ----------------------------- |
| `DEFAULT` | Formato padrão do Hub Message |

## Autenticação do webhook

Você pode configurar como o {projectName} se autentica ao chamar sua URL:

| Tipo            | Como funciona                                                   |
| --------------- | --------------------------------------------------------------- |
| `NONE`          | Sem autenticação (não recomendado em produção)                  |
| `BEARER`        | Envia `Authorization: Bearer <token>`                           |
| `API_KEY`       | Envia uma chave de API configurada                              |
| `BASIC`         | HTTP Basic Authentication (`username:password`)                 |
| `CUSTOM_HEADER` | Envia um header customizado com nome e valor definidos por você |

## Assinatura HMAC

Para garantir que as requisições recebidas são realmente do {projectName} e não foram adulteradas, habilite a assinatura HMAC configurando `signing: true` ao criar o webhook.

Quando habilitado:

* Um `secret` de 64 caracteres hexadecimais é gerado e retornado **apenas uma vez** na criação/atualização.
* Cada requisição enviada ao seu webhook inclui um header com a assinatura HMAC-SHA256 calculada sobre o payload.
* Você verifica a assinatura no seu servidor usando o `secret` armazenado.

<Warning>
  O `secret` é exibido **apenas** na resposta do `POST /webhooks` (criar) ou `PATCH /webhooks/{id}` (atualizar com `signing: true`). Armazene-o com segurança — ele não pode ser recuperado depois.
</Warning>

## Por canal

Cada webhook é associado a um canal específico via `channelId`. Um mesmo canal pode ter **múltiplos webhooks** com configurações diferentes — por exemplo, um para mensagens e outro para eventos de conexão.

## Gerenciamento

<CardGroup cols={2}>
  <Card title="Criar webhook" icon="plus" href="/webhooks/create-webhook">
    Registre um novo endpoint de webhook em um canal.
  </Card>

  <Card title="Listar webhooks" icon="list" href="/webhooks/list-webhooks">
    Veja todos os webhooks de um canal.
  </Card>

  <Card title="Atualizar webhook" icon="pen" href="/webhooks/update-webhook">
    Atualize URL, eventos, autenticação ou status.
  </Card>

  <Card title="Deletar webhook" icon="trash" href="/webhooks/delete-webhook">
    Remova um webhook de um canal.
  </Card>

  <Card title="Estrutura dos payloads" icon="brackets-curly" href="/webhooks/payloads">
    Exemplos reais dos payloads recebidos para cada tipo de mensagem.
  </Card>
</CardGroup>