Incoming message webhooks deliver real-time notifications when your recipients reply, enabling immediate responses and interactive conversations through WhatsApp.
The Incoming Messages system provides a robust webhook infrastructure that enables your application to receive and process WhatsApp messages from your recipients in real-time. This guide covers how to configure, manage, and handle incoming message webhooks.

​
Overview

Webhooks are HTTP callbacks that deliver notifications to your server whenever specific events occur - in this case, when recipients reply to your WhatsApp messages. Benefits include:
  • Real-time processing of customer responses
  • Seamless integration with your existing systems
  • Automated workflows triggered by customer messages
  • Enhanced customer experience through timely interactions

Try it in the API Reference

Explore the Webhook Management API and start receiving incoming messages

​
Webhook Configuration

​
Managing Endpoints

1

Access Webhook Settings

Navigate to the Developer section in your dashboard sidebar to manage webhook configurations.
2

Configure Endpoint

Add a new webhook URL where you want to receive incoming message notifications.

​
Endpoint Requirements

All webhook endpoints must be publicly accessible via HTTPS and configured to accept POST requests with JSON payloads. HTTP endpoints are not supported in production environments.
Your webhook endpoint must:
  1. Accept HTTP POST requests
  2. Process JSON payloads
  3. Return a 2xx status code within 10 seconds
  4. Implement idempotency handling (see best practices below)

​
Webhook Payload

When a user replies to your WhatsApp message, we’ll send a POST request to your configured endpoint with a detailed payload.

​
Sample Payload

{
  "last_messages": [
    {
      "type": "user",
      "content": "Thank you for the quick response. Can you provide more details about your premium service plans?",
      "timestamp": "2025-06-09T22:08:11.990Z",
      "content_type": "text"
    },
    {
      "type": "bot",
      "content": "I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
      "timestamp": "2025-06-09T21:45:30.417Z",
      "content_type": "text"
    }
  ],
  "conversation_paragraph": "User (10:08:11 PM): Thank you for the quick response. Can you provide more details about your premium service plans? ; Bot (9:45:30 PM): I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
  "phone_number": "14155552671",
  "recipient_name": "Sarah Johnson",
  "user_id": "9232fcef-a570-4a2c-b46b-6cab53aec304",
  "last_message_of_user": "Thank you for the quick response. Can you provide more details about your premium service plans?",
  "last_message_of_bot": "I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
  "message_type": "text",
  "user_last_message_time": 1749506891,
  "bot_last_message_time": 1749504330,
  "attachment_url": null,
  "note": "",
  "note_automation": "",
  "labels": "sales, premium-inquiry"
}

​
Payload Fields

​
last_messages
array
required
Array containing the recent messages in the conversation
​
conversation_paragraph
string
required
Human-readable summary of the recent conversation
​
phone_number
string
required
The phone number of the recipient who sent the message
​
recipient_name
string
The name of the recipient if available
​
user_id
string
required
Unique identifier for the user in your system
​
last_message_of_user
string
The last message sent by the user
​
last_message_of_bot
string
The last message sent by your system
​
message_type
string
required
The type of the latest message (text, image, audio, video, document, location)
​
user_last_message_time
integer
required
Unix timestamp of the user’s last message
​
bot_last_message_time
integer
required
Unix timestamp of your system’s last message
​
attachment_url
string
URL to media file if the latest message contains media (null for text messages)
​
note
string
Custom note field for additional context
​
note_automation
string
Automation-related notes
​
labels
string
Comma-separated labels for categorizing the conversation

​
Webhook Management API

You can programmatically manage your webhook endpoints using our API.

​
Create Webhook Endpoint

Register a new webhook endpoint to receive incoming message notifications. 
curl -X POST \
  https://api.insightssystem.com/api:qh9OQ3OW/webhook/dev/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "url": "https://your-domain.com/api/webhooks/whatsapp"
  }'
Always verify webhook signatures to ensure the authenticity of incoming requests. This prevents malicious actors from sending fraudulent events to your endpoint.

​
Troubleshooting

Webhook Not Receiving Events

​
FAQs

Need assistance?

Our technical support team is available to assist with webhook configuration, payload handling, and integration questions.