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

# Configure Webhook

> Receive real-time events from your instance via Webhook.

# Instance Webhook

Manage the configuration to receive notifications about messages, connections, and other events in real time on your server.

## <Icon icon="flask" size={22} /> Testing Tools

Before integrating, we recommend testing that the data is received. Use one of these tools to inspect the payload:

<CardGroup cols={3}>
  <Card href="https://webhook.cool/" title="Webhook.cool">
    <img src="https://icons.duckduckgo.com/ip3/webhook.cool.ico" width="40" className="mb-4" />

    **Recommended.** No rate limit and a super clean interface.
  </Card>

  <Card href="https://svix.com/play" title="SVIX">
    <img src="https://icons.duckduckgo.com/ip3/svix.com.ico" width="40" className="mb-4" />

    Good alternative. Reliable, with a low rate limit.
  </Card>

  <Card href="https://webhook.site/" title="Webhook.site">
    <img src="https://icons.duckduckgo.com/ip3/webhook.site.ico" width="40" className="mb-4" />

    Avoid if possible. It has very aggressive rate limits.
  </Card>
</CardGroup>

***

## <Icon icon="rocket" size={22} /> Simple Mode (Recommended)

This is the easiest way to configure it. The system automatically manages a single webhook per instance, creating or updating it as needed.

**Rules:**

1. Do not include `action` or `id` in the payload.
2. Always use filters to avoid infinite loops.

<Warning>
  **Loop Prevention**

  If you use automations, **always** include `"excludeMessages": ["wasSentByApi"]`. This prevents messages sent by your own bot from triggering new events, which would create an infinite loop.
</Warning>

### Payload Example

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

***

## <Icon icon="gear" size={22} /> Advanced Mode

Use this mode only if you need to register **multiple webhooks** for the same instance (e.g., one webhook for messages and another for connection status).

<Tip>
  **Pro Tip:** Even if you need multiple endpoints, consider using the **URL Parameters** feature (see the end of this page) with Simple Mode. It is easier to maintain.
</Tip>

### Manual Management

To control multiple webhooks, you must send the `action` field.

<CodeGroup>
  ```json Create (Add) theme={null}
  {
    "action": "add",
    "url": "https://api.site.com/webhook-1",
    "events": ["messages"]
    // O sistema gera um ID automaticamente
  }
  ```

  ```json Update (Update) theme={null}
  {
    "action": "update",
    "id": "ID_DO_WEBHOOK", // Obrigatório
    "url": "https://api.site.com/nova-url",
    "events": ["messages", "call"]
  }
  ```

  ```json Delete (Delete) theme={null}
  {
    "action": "delete",
    "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário
  }
  ```
</CodeGroup>

***

## Available Events

Select which types of notifications you want to receive in the `events` array.

<AccordionGroup>
  <Accordion title="Messages and Chats" icon="message">
    | Event | Description |
    | :- | :- |
    | `messages` | New messages received. |
    | `messages_update` | Status updates (delivered, read) or edits. |
    | `history` | Message history received upon connecting. |
    | `chats` | Events related to the chat list. |
    | `chat_labels` | Changes to chat labels. |
  </Accordion>

  <Accordion title="System and Connection" icon="server">
    | Event | Description |
    | :- | :- |
    | `connection` | State changes (QR Code, Connected, Disconnected). |
    | `presence` | Presence status changes (online, typing). |
    | `contacts` | Updates to the contact list. |
    | `groups` | Group changes (title, participants). |
    | `blocks` | Contact blocks and unblocks. |
    | `call` | Voice/video call events. |
  </Accordion>

  <Accordion title="Marketing and Leads" icon="bullhorn">
    | Event | Description |
    | :- | :- |
    | `leads` | Lead updates. |
    | `labels` | Label management. |
    | `sender` | Campaign updates (start/end). |
  </Accordion>
</AccordionGroup>

## Exclusion Filters (`excludeMessages`)

Use the `excludeMessages` field to ignore specific messages and save processing.

| Filter | Description |
| :- | :- |
| `wasSentByApi` | **Important:** Ignores messages sent by the API itself. |
| `wasNotSentByApi` | Ignores messages that were NOT sent by the API. |
| `fromMeYes` | Ignores messages sent by the user themselves (phone). |
| `fromMeNo` | Ignores messages received from other people. |
| `isGroupYes` | Ignores messages coming from groups. |
| `isGroupNo` | Ignores messages from private chats (DMs). |

***

## URL Parameters (Dynamic Routes)

You can have the API add information directly to your webhook URL, making routing easier in your backend (e.g., using Node.js/Express or Laravel Routes).

### Available Options

<CardGroup cols={2}>
  <Card title="addUrlEvents" icon="bolt">
    Adds the **event** to the URL.
    `.../webhook/{evento}`
  </Card>

  <Card title="addUrlTypesMessages" icon="envelope-open-text">
    Adds the **message type** to the URL.
    `.../webhook/{tipo}`
  </Card>
</CardGroup>

### Result Examples

Suppose your base URL is `https://api.example.com/webhook`:

1. **Events Only (`addUrlEvents: true`):**
   * `https://api.example.com/webhook/message`
   * `https://api.example.com/webhook/connection`

2. **Types Only (`addUrlTypesMessages: true`):**
   * `https://api.example.com/webhook/conversation` (text)
   * `https://api.example.com/webhook/image` (media)

3. **Both Enabled (Combination):**
   The order is always: `{URL_BASE}/{EVENTO}/{TIPO_MENSAGEM}`
   * `https://api.example.com/webhook/message/conversation`
   * `https://api.example.com/webhook/message/audio`

<Note>
  Make sure your backend is configured to accept **dynamic parameters** (wildcards) in the route to process these URLs correctly.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.