Configuring Default Response Webhooks in WhatsApp Business API

Webhooks for WhatsApp Default Response Configuration allow you to receive real-time notifications when default responses are sent to customers. This enables integration with your CRM systems, logging platforms, analytics tools, and custom business applications.

What is a Webhook?

A webhook is an HTTP callback that sends data to a specified URL when a specific event occurs. In the context of default responses, the webhook is triggered automatically when a default response message is sent to a customer.

Benefits of Using Webhooks:

1. Real-time Notifications: Get instant alerts when default responses are sent
2. CRM Integration: Automatically log interactions in your CRM system
3. Analytics Tracking: Track default response usage and effectiveness
4. Custom Processing: Trigger additional business logic based on default responses
5. Audit Trail: Maintain comprehensive logs of all default response activities
6. Automation: Integrate with workflow automation tools

How to Configure Webhooks

Step 1: Prepare Your Webhook Endpoint

Before configuring the webhook in the platform, ensure you have:

1. A publicly accessible URL endpoint
2. HTTPS enabled (required for security)
3. Server capable of receiving POST requests
4. Proper authentication mechanism (recommended)

Example Webhook URL:

https://yourdomain.com/webhooks/whatsapp-default-response

Step 2: Configure Webhook in Default Response Setup

1. Navigate to WhatsApp > Default Response Configuration > Add/Edit
2. Scroll to the Default Message Webhook field
3. Enter your webhook URL in the format: https://example.com/myscript/
4. Ensure the URL:
   • Starts with https://
   • Is publicly accessible
   • Can receive POST requests
   • Has proper SSL certificate

Step 3: Webhook URL Format

Correct Format:

https://example.com/webhook-handler/
https://api.yourcompany.com/whatsapp/default-response
https://yourdomain.com/hooks/wa-default

Incorrect Format:

http://example.com/webhook (HTTP not allowed)
example.com/webhook (Missing protocol)
localhost/webhook (Not publicly accessible)

Step 4: Test Your Webhook

After saving the configuration, test your webhook:

1. Trigger a default response by sending a test message
2. Check your webhook endpoint logs
3. Verify the data received matches expected format
4. Ensure your server responds with HTTP 200 status

Webhook Payload Structure

When a default response is sent, your webhook will receive a POST request with JSON data. The exact structure may vary, but typically includes:

{
  "event": "default_response_sent",
  "timestamp": "2025-10-09T12:34:56Z",
  "waba_number": "+1234567890",
  "recipient": "+0987654321",
  "message_type": "text",
  "message_content": "Your default response message",
  "message_id": "wamid.xxx",
  "user_id": 12345,
  "config_id": 67890
}

Webhook Security Best Practices

1. Use HTTPS: Always use encrypted connections
2. Implement Authentication: Use API keys, tokens, or signatures
3. Validate Requests: Verify webhook requests are from legitimate sources
4. Rate Limiting: Implement rate limiting to prevent abuse
5. Error Handling: Handle errors gracefully and log failures
6. IP Whitelisting: Restrict access to known IP addresses (if possible)

Example Webhook Handler (PHP)

<?php
// webhook-handler.php

// Verify request (add your authentication logic)
$apiKey = $_SERVER['HTTP_X_API_KEY'] ?? '';
if ($apiKey !== 'your-secret-api-key') {
    http_response_code(401);
    exit('Unauthorized');
}

// Get webhook data
$data = json_decode(file_get_contents('php://input'), true);

// Log the webhook
error_log('Default Response Webhook: ' . json_encode($data));

// Process the webhook
if (isset($data['event']) && $data['event'] === 'default_response_sent') {
    // Your business logic here
    // e.g., Update CRM, send notification, etc.
}

// Respond to webhook
http_response_code(200);
echo json_encode(['status' => 'success']);
?>

Example Webhook Handler (Node.js)

// webhook-handler.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/default-response', (req, res) => {
  // Verify authentication
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== 'your-secret-api-key') {
    return res.status(401).send('Unauthorized');
  }

  // Process webhook data
  const data = req.body;
  console.log('Default Response Webhook:', data);

  // Your business logic here
  // e.g., Update database, trigger workflow, etc.

  // Respond
  res.status(200).json({ status: 'success' });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Common Use Cases

1. CRM Integration:

• Log customer interactions automatically
• Update customer records with conversation history
• Trigger follow-up tasks in CRM

2. Analytics and Reporting:

• Track default response usage statistics
• Measure response effectiveness
• Generate automated reports

3. Notification Systems:

• Send alerts to team members
• Notify managers of customer interactions
• Integrate with Slack, Teams, or email

4. Business Logic Automation:

• Trigger additional workflows
• Update inventory systems
• Sync with e-commerce platforms

5. Audit and Compliance:

• Maintain comprehensive logs
• Ensure regulatory compliance
• Track all customer communications

Troubleshooting Webhook Issues

Issue: Webhook not receiving requests

• Check: Verify URL is publicly accessible and HTTPS enabled
• Check: Ensure firewall allows incoming connections
• Check: Test URL manually with a POST request

Issue: 401/403 Errors

• Check: Verify authentication credentials
• Check: Ensure API keys/tokens are correct
• Check: Review server access logs

Issue: Timeout Errors

• Check: Ensure webhook responds within timeout period
• Check: Optimize webhook processing time
• Check: Consider asynchronous processing

Issue: Invalid Data Format

• Check: Verify JSON parsing logic
• Check: Handle missing or unexpected fields
• Check: Validate data structure

Testing Your Webhook

1. Manual Testing:
   • Use tools like Postman or cURL
   • Send test POST requests to your endpoint
   • Verify response handling
2. Logging:
   • Enable detailed logging
   • Monitor webhook requests
   • Track errors and failures
3. Monitoring:
   • Set up alerts for webhook failures
   • Monitor response times
   • Track success rates

Best Practices:

1. Always Use HTTPS: Security is paramount
2. Implement Retry Logic: Handle temporary failures
3. Validate Data: Verify webhook payload structure
4. Log Everything: Maintain comprehensive logs
5. Monitor Performance: Track webhook response times
6. Error Handling: Gracefully handle all error scenarios
7. Documentation: Document your webhook endpoints

Next Steps:

After configuring webhooks, learn about managing and updating your default response configurations in our “Managing Default Response Configurations” guide.