Instance Webhook

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

Testing Tools

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

Webhook.cool

Recommended. No rate limit and a super clean interface.

SVIX

Good alternative. Reliable, with a low rate limit.

Webhook.site

Avoid if possible. It has very aggressive rate limits.

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:

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

Loop PreventionIf 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.

Payload Example

{
  "url": "[https://meusite.com/webhook](https://meusite.com/webhook)",
  "events": [
    "messages",
    "connection"
  ],
  "excludeMessages": [
    "wasSentByApi"
  ]
}

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).

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.

Manual Management

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

{
  "action": "add",
  "url": "[https://api.site.com/webhook-1](https://api.site.com/webhook-1)",
  "events": ["messages"]
  // O sistema gera um ID automaticamente
}

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

{
  "action": "delete",
  "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário
}

Available Events

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

Messages and Chats

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.

System and Connection

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.

Marketing and Leads

Event	Description
`leads`	Lead updates.
`labels`	Label management.
`sender`	Campaign updates (start/end).

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

addUrlEvents

Adds the event to the URL. .../webhook/{evento}

addUrlTypesMessages

Adds the message type to the URL. .../webhook/{tipo}

Result Examples

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

Events Only (addUrlEvents: true):
- https://api.example.com/webhook/message
- https://api.example.com/webhook/connection
Types Only (addUrlTypesMessages: true):
- https://api.example.com/webhook/conversation (text)
- https://api.example.com/webhook/image (media)
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

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

Getting Started

Configure Webhook

Instance Webhook

Testing Tools

Webhook.cool

SVIX

Webhook.site

Simple Mode (Recommended)

Payload Example

Advanced Mode

Manual Management

Available Events

Exclusion Filters (`excludeMessages`)

URL Parameters (Dynamic Routes)

Available Options

addUrlEvents

addUrlTypesMessages

Result Examples

​Instance Webhook

​ Testing Tools

Webhook.cool

SVIX

Webhook.site

​ Simple Mode (Recommended)

​Payload Example

​ Advanced Mode

​Manual Management

​Available Events

​Exclusion Filters (excludeMessages)

​URL Parameters (Dynamic Routes)

​Available Options

addUrlEvents

addUrlTypesMessages

​Result Examples

Instance Webhook

Testing Tools

Simple Mode (Recommended)

Payload Example

Advanced Mode

Manual Management

Available Events

Exclusion Filters (`excludeMessages`)

URL Parameters (Dynamic Routes)

Available Options

Result Examples