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

# Webhooks

{document.querySelectorAll("#footer > div.flex.items-center.justify-between > div").forEach((a) => a.remove())}

## Ferramentas de Teste

Para testar webhooks durante o desenvolvimento, recomendamos estas ferramentas:

<CardGroup cols={3}>
  <Card title="Webhook.cool" icon="star" href="[https://webhook.cool/](https://webhook.cool/)" color="#16a34a">
    **Melhor opção.** Sem rate limit e interface limpa.
  </Card>

  <Card title="Rbaskets.in" icon="check" href="[https://rbaskets.in/](https://rbaskets.in/)" color="#2563eb">
    **Boa alternativa.** Confiável e baixo rate limit.
  </Card>

  <Card title="Webhook.site" icon="triangle-exclamation" href="[https://webhook.site/](https://webhook.site/)" color="#dc2626">
    **Evitar.** Rate limit agressivo pode bloquear testes.
  </Card>
</CardGroup>

***

## Modos de Configuração

<Tabs>
  <Tab title="🚀 Modo Simples (Recomendado)">
    O modo simples gerencia automaticamente um único webhook por instância, criando ou atualizando conforme necessário.

    <Steps>
      <Step title="Simplifique">
        Não inclua `action` nem `id` no payload.
      </Step>

      <Step title="Evite Loops">
        Sempre use `excludeMessages` com `"wasSentByApi"`.
      </Step>
    </Steps>

    ```json Exemplo de Payload theme={null}
    {
      "url": "https://meusite.com/webhook",
      "events": ["messages"],
      "excludeMessages": ["wasSentByApi"]
    }
    ```

    <Tip>
      **Dica:** Mesmo no modo simples, você pode usar `addUrlEvents` (veja no final da página) para rotear eventos para URLs diferentes (ex: `/webhook/messages`) sem criar múltiplos webhooks manuais.
    </Tip>
  </Tab>

  <Tab title="⚙️ Modo Avançado">
    Para usuários que precisam registrar **múltiplos webhooks** distintos para a mesma instância.

    **Ações (`action`):**

    * `add`: Registrar novo (não envie ID).
    * `update`: Atualizar existente (envie ID).
    * `delete`: Remover (envie apenas ID).

    ```json Exemplo de Payload theme={null}
    {
      "action": "add",
      "url": "https://api.crm.com/leads",
      "events": ["leads"],
      "excludeMessages": ["wasSentByApi"]
    }
    ```
  </Tab>
</Tabs>

***

## Prevenção de Loops

<Warning>
  **Importante: Evite Loops Infinitos**

  Se sua automação envia mensagens via API, sua aplicação **deve** ignorar os eventos dessas mensagens para não responder a si mesma infinitamente.

  Sempre inclua: `"excludeMessages": ["wasSentByApi"]`
</Warning>

***

## Referência Técnica

<AccordionGroup>
  <Accordion title="Eventos Disponíveis" icon="satellite-dish">
    | Evento            | Descrição                                  |
    | :---------------- | :----------------------------------------- |
    | `messages`        | Novas mensagens recebidas.                 |
    | `messages_update` | Atualizações em mensagens (ex: deletadas). |
    | `connection`      | Alterações no estado da conexão.           |
    | `history`         | Recebimento de histórico.                  |
    | `call`            | Eventos de chamadas VoIP.                  |
    | `contacts`        | Atualizações na agenda.                    |
    | `presence`        | Alterações no status (digitando...).       |
    | `groups`          | Modificações em grupos.                    |
    | `labels`          | Gerenciamento de etiquetas.                |
    | `chats`           | Eventos de conversas.                      |
    | `blocks`          | Bloqueios/desbloqueios.                    |
    | `leads`           | Atualizações de leads.                     |
    | `sender`          | Atualizações de campanhas.                 |
  </Accordion>

  <Accordion title="Filtros (excludeMessages)" icon="filter">
    * `wasSentByApi`: **(Importante)** Mensagens originadas pela API.
    * `wasNotSentByApi`: Mensagens não originadas pela API.
    * `fromMeYes`: Mensagens enviadas pelo usuário.
    * `fromMeNo`: Mensagens recebidas de terceiros.
    * `isGroupYes`: Mensagens em grupos.
    * `isGroupNo`: Mensagens em conversas individuais.
  </Accordion>
</AccordionGroup>

***

## URL Dinâmica

Adicione parâmetros à URL do webhook para facilitar o roteamento no backend.

<CodeGroup>
  ```json Apenas Eventos theme={null}
  // URL: .../webhook/{evento}
  { "addUrlEvents": true }
  ```

  ```json Apenas Tipos theme={null}
  // URL: .../webhook/{tipo_mensagem}
  { "addUrlTypesMessages": true }
  ```

  ```json Ambos (Combinados) theme={null}
  // URL: .../webhook/{evento}/{tipo_mensagem}
  // Exemplo: .../webhook/message/conversation
  {
    "addUrlEvents": true,
    "addUrlTypesMessages": true
  }
  ```
</CodeGroup>