Webhooks send real-time HTTP notifications when something happens on WhatsApp — new messages, connection changes, QR updates, and more. Use them to power bots, CRM sync, and n8n triggers without polling the API.

When you need webhooks

• Auto-reply to incoming WhatsApp messages
• Push leads into a CRM when a customer writes you
• Start an n8n workflow when connection drops or QR refreshes
• Log all message events to your own database

If you only send occasional outbound messages, you may not need webhooks.

How it works (high level)

1. You provide a public HTTPS URL on your server or automation platform.
2. You register that URL for your WhatsApp instance (or globally for all instances).
3. When an event occurs, your workspace sends a POST request with a JSON payload to your URL.
4. Your endpoint returns a success status so delivery is acknowledged.

Configure from Aysali Manager

The simplest path for many users:

1. Open WhatsApp → Open Manager (Aysali Manager).
2. Select your instance.
3. Open Webhook or Events settings (exact menu label in Manager).
4. Enter your URL and select events (for example MESSAGES_UPSERT, CONNECTION_UPDATE).
5. Save and send a test message to verify your endpoint receives payloads.

Common events

Event	Typical use
QRCODE_UPDATED	Display QR in your own UI during linking
CONNECTION_UPDATE	Alert when WhatsApp disconnects
MESSAGES_UPSERT	New or updated incoming/outgoing messages
MESSAGES_UPDATE	Delivery or read receipts
SEND_MESSAGE	Confirm outbound sends

Full event list and payload shapes are documented in the API reference.

Tips

• Start with one or two events to avoid flooding your endpoint during testing.
• Validate and parse JSON safely; ignore unknown fields for forward compatibility.
• Respond quickly (under a few seconds); do heavy processing asynchronously.
• Use a secret or signature verification if your integration supports it.

Troubleshooting

Issue	What to try
No callbacks received	Confirm URL is HTTPS and publicly reachable; check firewall
404 on webhook path	Ensure your route matches the exact path you registered
Duplicate events	Make webhook handler idempotent using message IDs
Only some events fire	Re-check selected events list in Manager or API config

For developers

Related