Receiving messages via webhooks

Webhooks send real-time HTTP notifications to your server when events happen in AIsoule.

What are webhooks?

Instead of polling the API repeatedly, webhooks push data to your server instantly when:

• A new message arrives
• A message is delivered or read
• A contact is created or updated
• A campaign completes
• An agent transfer happens

Setting up a webhook

1. Go to Settings → Webhooks
2. Click "New Webhook"
3. Configure:
   • Name — Descriptive name (e.g., "CRM Sync")
   • URL — Your server endpoint (must be HTTPS)
   • Events — Select which events to receive
   • Secret — Auto-generated HMAC secret for verification
4. Click Save

Available events

Webhook payload format

{
  "event": "message.incoming",
  "timestamp": "2026-05-29T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "+919876543210",
    "contact_name": "John Doe",
    "type": "text",
    "text": "Hello, I need help with my order",
    "whatsapp_account_id": "uuid"
  }
}

Verifying webhook signatures

Every webhook request includes an HMAC-SHA256 signature in the X-Webhook-Signature header.

To verify:

1. Get the raw request body
2. Compute HMAC-SHA256 using your webhook secret
3. Compare with the X-Webhook-Signature header

import hmac, hashlib

def verify_signature(body, signature, secret):
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Requirements for your endpoint

• Must respond with HTTP 200 within 5 seconds
• Must accept POST requests
• Must use HTTPS (HTTP not supported)
• Should be idempotent (same event may be sent twice)

Retry policy

If your endpoint doesn't respond with 200:

• AIsoule retries 3 times with exponential backoff
• Delays: 10 seconds, 60 seconds, 5 minutes
• After 3 failures, the webhook is marked as failing

Testing webhooks

Use tools like webhook.site or ngrok to test locally:

1. Get a temporary HTTPS URL from webhook.site
2. Set it as your webhook URL in AIsoule
3. Send a test message to your WhatsApp number
4. See the webhook payload arrive in real-time

Tips

1. Respond quickly — Process asynchronously, respond 200 immediately
2. Handle duplicates — Use message_id to deduplicate
3. Monitor failures — Check webhook status in Settings → Webhooks
4. Use the secret — Always verify signatures in production
5. Log everything — Store raw payloads for debugging