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.

3

Set Up Authentication

We recommend implementing signature verification to ensure webhook security.

4

Test Your Endpoint

Use the test feature to verify your webhook is properly receiving and processing events.

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

{
  "event_type": "incoming_message",
  "event_id": "evt_1nHs82jKla92mzP",
  "timestamp": "2025-04-15T13:42:27Z",
  "data": {
    "conversation_id": "conv_87Hj2k9Lm5",
    "phone_number": "8801734363287",
    "recipient_name": "John Doe",
    "user_id": "6fb11ff2-d9b2-4560-8437-0fe58ec9f4a6",
    "message": {
      "type": "text",
      "content": "How can I use notifier by whatsable api?",
      "timestamp": "2025-04-15T13:42:27Z"
    },
    "conversation_context": {
      "last_user_message": "How can I use notifier by whatsable api?",
      "last_bot_message": "Hello! How can I assist you today?",
      "user_timestamp": 1718470947,
      "bot_timestamp": 1718470865
    },
    "conversation_history": [
      {
        "type": "bot",
        "content": "Hello! How can I assist you today?",
        "timestamp": "2025-04-15T13:41:05Z",
        "content_type": "text"
      },
      {
        "type": "user",
        "content": "How can I use notifier by whatsable api?",
        "timestamp": "2025-04-15T13:42:27Z",
        "content_type": "text"
      }
    ]
  },
  "version": "2025-04-01"
}

Payload Fields

event_type
string
required

Type of event, always “incoming_message” for incoming messages

event_id
string
required

Unique identifier for the event, use this for deduplication

timestamp
string
required

ISO 8601 timestamp when the event occurred

data
object
required
version
string
required

API version identifier

Webhook Management API

You can programmatically manage your webhook endpoints using our API.

List Webhook Endpoints

Retrieve all configured webhook endpoints for your account.

curl -X GET \
  https://api.insightssystem.com/api:AFRA_QCy/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create Webhook Endpoint

Register a new webhook endpoint to receive incoming message notifications.

curl -X POST \
  https://api.insightssystem.com/api:AFRA_QCy/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "url": "https://example.com/webhooks/whatsapp",
    "description": "Production webhook for WhatsApp replies",
    "events": ["incoming_message"]
  }'

Webhook Security

Always verify webhook signatures to ensure the authenticity of incoming requests. This prevents malicious actors from sending fraudulent events to your endpoint.

Signature Verification

Every webhook request includes a signature in the X-Webhook-Signature header. Verify this signature by:

  1. Extract the X-Webhook-Signature header value
  2. Compute an HMAC-SHA256 signature using your webhook secret and the raw request body
  3. Compare the computed signature with the header value
const crypto = require('crypto');

function verifyWebhookSignature(requestBody, signatureHeader, webhookSecret) {
  const hmac = crypto.createHmac('sha256', webhookSecret);
  const signature = hmac.update(requestBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(signatureHeader, 'hex')
  );
}

// Express.js example
app.post('/webhooks/whatsapp', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  
  if (!signature) {
    return res.status(400).send('No signature header');
  }
  
  const isValid = verifyWebhookSignature(
    req.body.toString(),
    signature,
    'YOUR_WEBHOOK_SECRET'
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  const payload = JSON.parse(req.body.toString());
  // Process the webhook payload
  
  res.status(200).send('Webhook received');
});

Best Practices

Idempotency

Implement idempotency key checks to prevent duplicate processing of events. Use the event_id field to detect and handle retries.

Graceful Error Handling

Design your webhook handler to gracefully process unexpected payload structures or event types. This ensures compatibility with future API updates.

Quick Response

Always respond quickly with a 2xx status code, then process the webhook asynchronously. Responses taking longer than 10 seconds may cause webhook delivery retries.

Multiple Endpoints

Consider configuring multiple webhook endpoints for different environments (development, staging, production) or different types of processing.

Handling Media Files

When receiving media messages:

  1. Download the media file from the URL provided in the webhook as soon as possible
  2. Media URLs expire after 24 hours
  3. Verify the SHA-256 hash to ensure file integrity
  4. Store media files securely in your system
const axios = require('axios');
const fs = require('fs');
const crypto = require('crypto');
const path = require('path');

async function downloadAndVerifyMedia(mediaUrl, expectedSha256) {
  try {
    // Download the file
    const response = await axios({
      method: 'GET',
      url: mediaUrl,
      responseType: 'arraybuffer'
    });
    
    // Calculate SHA-256 hash
    const fileBuffer = Buffer.from(response.data);
    const calculatedHash = crypto
      .createHash('sha256')
      .update(fileBuffer)
      .digest('hex');
    
    // Verify hash
    if (calculatedHash !== expectedSha256) {
      throw new Error('File hash verification failed');
    }
    
    // Save file
    const filename = `media_${Date.now()}${path.extname(mediaUrl)}`;
    fs.writeFileSync(filename, fileBuffer);
    
    return filename;
  } catch (error) {
    console.error('Error downloading media:', error);
    throw error;
  }
}

Rate Limiting and Quotas

Testing Webhooks

Test your webhook implementation before going live:

  1. Create a test webhook endpoint using a service like webhook.site or Beeceptor
  2. Configure this test URL in your webhook settings
  3. Send a test WhatsApp message to trigger the webhook
  4. Inspect the payload to understand the data structure
  5. Implement proper handling in your application

Always test your webhook implementation thoroughly in a development environment before configuring production endpoints.

Troubleshooting

FAQs

Need help?

Our support team is available 24/7 to assist with webhook setup, event handling, or any other questions.

2025-04-10
v2.1.0

Enhanced Webhook System

  • Added signature verification for improved security
  • Extended media file expiration to 24 hours (previously 1 hour)
  • Improved retry logic for failed webhook deliveries
  • Added support for multiple endpoints per account
2025-02-28
v2.0.0

Major Webhook Overhaul

  • Standardized event payload structure
  • Added conversation history context
  • Improved media handling capabilities
  • Added programmatic webhook management API