Configure Instance Webhook

Manages the configuration of webhooks to receive real-time instance events. Allows managing multiple webhooks per instance via the ID and action fields.

🚀 Simple Mode (Recommended)

Easiest usage - no ID complexity:

• Do not include action or id in the payload
• Automatically manages a single webhook per instance
• Automatically creates a new one or updates the existing one
• Recommended: Always use "excludeMessages": ["wasSentByApi"] to avoid loops
• Example: {"url": "https://mysite.com/webhook", "events": ["messages"], "excludeMessages": ["wasSentByApi"]}

🧪 Testing Sites (ranked by quality)

To test webhooks during development:

1. https://webhook.cool/ - ⭐ Best option (no rate limit, clean interface)
2. https://rbaskets.in/ - ⭐ Good alternative (reliable, low rate limit)
3. https://webhook.site/ - ⚠️ Avoid if possible (aggressive rate limit)

⚙️ Advanced Mode (For multiple webhooks)

For users who need multiple webhooks per instance:

💡 Tip: Even if you need multiple webhooks, consider using addUrlEvents in simple mode. A single webhook can receive different event types at specific URLs (e.g., /webhook/message, /webhook/connection), eliminating the need for multiple webhooks.

1. Create New Webhook:

   • Use action: "add"
   • Do not include id in payload
   • System generates ID automatically

2. Update Existing Webhook:

   • Use action: "update"
   • Include the webhook id in payload
   • All fields will be updated

3. Remove Webhook:

   • Use action: "delete"
   • Include only the webhook id
   • Other fields are ignored

Available Events

• connection: Changes in connection state
• history: Receiving message history
• messages: New messages received
• messages_update: Updates to existing messages
• call: VoIP call events
• contacts: Contact list updates
• presence: Presence status changes
• groups: Group modifications
• labels: Label management
• chats: Chat events
• chat_labels: Chat label changes
• blocks: Blocks/unblocks
• leads: Lead updates
• sender: Campaign updates, when started, and when completed

Filter out messages based on filters:

• wasSentByApi: Messages originated by the API ⚠️ IMPORTANT: Always use this filter to avoid loops in automations
• wasNotSentByApi: Messages not originated by the API
• fromMeYes: Messages sent by the user
• fromMeNo: Messages received from others
• isGroupYes: Messages in groups
• isGroupNo: Messages in individual chats

💡 Loop Prevention: If you have automations that send messages via API, always include "excludeMessages": ["wasSentByApi"] in your webhook. If you prefer receiving these events, ensure your automation detects messages sent by the API itself to avoid infinite loops.

Supported Actions:

• add: Register new webhook
• delete: Remove existing webhook

URL Parameters:

• addUrlEvents (boolean): When active, adds the event type as a path parameter in the URL. Example: https://api.example.com/webhook/{event}
• addUrlTypesMessages (boolean): When active, adds the message type as a path parameter in the URL. Example: https://api.example.com/webhook/{message_type}

Parameter Combinations:

• Both active: https://api.example.com/webhook/{event}/{message_type} Real example: https://api.example.com/webhook/message/conversation
• Events only: https://api.example.com/webhook/message
• Types only: https://api.example.com/webhook/conversation

Technical Notes:

1. Parameters are added in the order: event → message type
2. The URL must be configured to accept these dynamic parameters
3. Works with any combination of events/messages