Messages Webhook
Webhooks allow you to receive real-time notifications when events occur in your MAIA channels. When an AI agent responds to a message or a human operator sends a reply, MAIA will send an HTTP POST request to your configured webhook URL. Optionally, you can also receive incoming customer messages and echo messages (sent from the connected phone) via the same webhook.
How Webhooks Work
Webhook Events
Webhooks are triggered for:
| Event | Direction | Description |
|---|---|---|
| AI Response | outgoing | When an AI agent generates a response to a customer message |
| Human Reply | outgoing | When an operator manually sends a message through the channel |
| Incoming Message | incoming | When a customer sends a message (requires Forward incoming messages toggle) |
| Echo Message | echo | When the phone owner sends a message directly from their device (requires Forward incoming messages toggle, non-official WhatsApp channels only) |
Test Sessions
Webhooks are not triggered for test sessions (sessions created via the test panel in the UI).
Configuring Webhooks
- Navigate to Channels in the MAIA dashboard
- Select the channel to configure
- In the channel settings, enter your Webhook URL
- Optionally, enable Forward incoming messages to webhook to also receive customer messages
- Save changes
A webhook secret will be automatically generated.
Incoming & Echo Messages
When Forward incoming messages is enabled, both incoming customer messages and echo messages (sent from the connected phone) are forwarded to the same webhook URL. Use the direction field in the payload to distinguish between "incoming", "outgoing", and "echo" messages. See Payload Reference for details.
Echo messages are only available for non-official WhatsApp channels. The official WhatsApp Business API does not relay messages sent from the phone.
Requirements
| Requirement | Details |
|---|---|
| Protocol | HTTPS only (HTTP not allowed) |
| Method | Must accept POST requests |
| Response | Return 2xx status within 10 seconds |
| Content-Type | Expect application/json |
Delivery Behavior
- Timeout: 10 seconds per request
- Retries: Up to 3 attempts with exponential backoff
- Retry delays: 1s → 2s → 4s
- Retried errors: 5xx responses, timeouts, network errors, 429 (rate limit)
- Not retried: 4xx errors (except 429)
Error Handling
Webhook delivery failures don't affect message delivery. If your webhook is down, messages are still sent to the customer—you just won't receive the notification.
Next Steps
- CRM Webhooks - Subscribe to CRM events (record created, field updates, etc.)
- Payload Reference - Understand the channel webhook payload structure
- Security - Verify webhook signatures