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

# API de Webhooks: Notificações em Tempo Real do PanÐá Zap

> Configure os webhooks do PanÐá Zap para receber notificações push instantâneas de mensagens, eventos de tickets e confirmações de entrega em tempo real.

Em vez de fazer polling na API em busca de novas atividades, você pode configurar o PanÐá Zap para enviar eventos ao seu servidor no momento em que algo acontece — uma nova mensagem chega, o status de um ticket muda, uma mensagem é entregue, ou uma mensagem é lida. Isso é chamado de **webhook**.

***

## Como os webhooks funcionam

Quando um evento de disparo ocorre, o PanÐá Zap envia uma requisição HTTP `POST` para a URL que você configurou. Seu servidor deve responder com um código de status `2xx`. Atualmente, o PanÐá Zap não tenta reenviar entregas que falharam, então garanta que seu endpoint seja confiável e responda rapidamente.

Existem dois tipos de webhooks:

| Tipo                 | Escopo                                                       | Onde configurar                       |
| -------------------- | ------------------------------------------------------------ | ------------------------------------- |
| **Webhook de canal** | Disparado quando um canal específico recebe uma mensagem.    | Administração → Canais → editar canal |
| **Webhooks globais** | Disparado para múltiplos tipos de evento em todos os canais. | Configurações → API → Webhooks        |

***

## Configurar um webhook de canal

<Steps>
  ### Abra as configurações do canal

  Vá para **Administração → Canais** e clique no ícone de edição do canal que deseja configurar.

  ### Ative o webhook

  Ative a chave **Webhook de Canal** para revelar os campos de configuração.

  ### Insira sua URL de webhook

  Cole a URL HTTPS pública para a qual o PanÐá Zap deve enviar os eventos. A URL deve ser publicamente acessível — localhost e endereços de rede interna não são suportados.

  ### Ative mensagens recebidas

  Ative **Mensagens Recebidas** para receber um payload de evento sempre que o canal receber uma mensagem de entrada.

  ### Salve

  Clique em **Salvar**. O PanÐá Zap começará imediatamente a enviar eventos para sua URL.
</Steps>

***

## Payload de evento de mensagem

Quando uma mensagem chega em um canal com webhooks ativados, o PanÐá Zap envia um payload semelhante ao seguinte:

```json theme={null}
{
  "method": "message",
  "msg": {
    "id": "wamid.xxxx",
    "body": "Hello, I need help with my order.",
    "fromMe": false,
    "timestamp": 1700000000,
    "type": "chat",
    "contact": {
      "name": "Maria Silva",
      "number": "5511999999999",
      "instagramPK": null,
      "messengerId": null,
      "telegramId": null
    }
  },
  "ticket": {
    "id": 1262,
    "status": "pending",
    "queueId": 3,
    "whatsappId": 12
  }
}
```

| Campo           | Descrição                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------- |
| `method`        | Sempre `"message"` para eventos de mensagens recebidas.                                     |
| `msg.id`        | ID único da mensagem do provedor do canal.                                                  |
| `msg.body`      | Conteúdo de texto da mensagem.                                                              |
| `msg.fromMe`    | `true` se a mensagem foi enviada pela sua conta; `false` para mensagens recebidas.          |
| `msg.timestamp` | Timestamp Unix da mensagem.                                                                 |
| `msg.type`      | Tipo de mensagem: `chat`, `image`, `audio`, `video`, `document`, etc.                       |
| `msg.contact`   | Informações do contato. Canais que não são WhatsApp preenchem o campo de ID correspondente. |
| `ticket.id`     | ID do ticket associado no PanÐá Zap.                                                        |
| `ticket.status` | Status atual do ticket no momento do evento.                                                |

<Note>
  `ticket.id` está sempre presente no payload do webhook para todos os tipos de canal — WhatsApp, Instagram, Messenger, Telegram e e-mail. Você sempre pode usá-lo para correlacionar o evento com um registro de ticket através da [API de Tickets](/api/tickets).
</Note>

***

## Configurar webhooks globais

Os webhooks globais permitem que você assine múltiplos tipos de evento em toda a sua conta — não apenas em um canal.

1. Vá para **Configurações → API**.
2. Ative a chave **Webhooks**.
3. Insira sua URL de webhook.
4. Ative **Mensagens de Webhook** se quiser receber eventos de mensagens.
5. Em **Eventos de Canal e Usuário**, ative os tipos de evento individuais que você precisa:
   * Criar / Atualizar Canal
   * Criar / Atualizar Usuário
   * Criar / Atualizar / Renovar API
6. Clique em **Salvar**.

**Tipos de evento globais disponíveis:**

| Evento                             | Disparado quando                                   |
| ---------------------------------- | -------------------------------------------------- |
| Novas mensagens                    | Qualquer mensagem é enviada ou recebida.           |
| Ticket aberto                      | Um novo ticket é criado.                           |
| Mudança de status do ticket        | Um ticket muda entre `open`, `pending` e `closed`. |
| Confirmação de entrega da mensagem | Uma mensagem chega ao dispositivo do destinatário. |
| Confirmação de leitura da mensagem | Uma mensagem é lida pelo destinatário.             |

<Tip>
  Assine apenas os eventos que você realmente utiliza. Toda chamada de webhook adiciona carga ao seu servidor — eventos desnecessários desperdiçam largura de banda e aumentam o overhead de processamento.
</Tip>

***

## Segurança

As URLs de webhook devem ser publicamente acessíveis via HTTPS. Por padrão, o PanÐá Zap não envia um cabeçalho de assinatura. Para proteger seu endpoint:

* **Restringir por IP**: configure seu servidor ou firewall para aceitar apenas requisições `POST` vindas dos endereços IP de saída do PanÐá Zap.
* **Token secreto na URL**: incorpore um token longo e aleatório no caminho da URL ou como um parâmetro de consulta (por exemplo, `https://yourserver.com/hooks/panda-zap?token=abc123`). Verifique sua presença em toda requisição recebida.

***

## Alternativa de polling

Se sua infraestrutura não pode expor um endpoint HTTPS público, você pode fazer polling na API periodicamente:

```http theme={null}
GET https://{BaseUrl}/v2/api/external/{ApiID}/listTickets?status=open
```

```http theme={null}
POST https://{BaseUrl}/v2/api/external/{ApiID}/showAllMessages
```

Faça polling em um intervalo razoável (por exemplo, a cada 30–60 segundos) para evitar atingir limites de taxa. Os webhooks são fortemente preferíveis para casos de uso sensíveis à latência.

***

## Correlacionando eventos com seus registros

Inclua um `externalKey` único em toda requisição de API que envia uma mensagem. Quando o webhook de entrega disparar, o payload conterá o mesmo `externalKey` — use-o para relacionar o evento do webhook de volta ao registro de envio original no seu sistema, sem depender de IDs internos do PanÐá Zap.