WhatsApp Webhook Setup Guide for Integration

Introduction

This guide will help you create a webhook endpoint to receive WhatsApp notifications from EasySocial. You only need to prepare your webhook endpoint - the rest of the webhook configuration is handled by EasySocial's support team.

⏱️ Estimated Setup Time: 15-30 minutes

👥 Target Audience: Integration partners implementing webhook endpoints

📋 What You'll Need: - A server or cloud service to receive webhook notifications - Basic understanding of HTTP requests and responses - Access to your server for code deployment

What Are Webhooks?

Simple Explanation

Webhooks are like "text messages" from EasySocial to your system. When WhatsApp events happen (messages, payments, status updates), EasySocial automatically sends notifications to your server.

How it works:

WhatsApp Message → EasySocial → Your Server (Webhook)

Payment Received → EasySocial → Your Server (Webhook)

Status Update → EasySocial → Your Server (Webhook)

Why You Need This?

• Real-time Updates: Get instant notifications
• No Polling: No need to constantly check for updates
• Reliable: Never miss important events

Prerequisites

Technical Requirements

Your Server Must Be Able To:

✅ Receive HTTP POST requests
✅ Process JSON payloads
✅ Respond with HTTP 200 status code
✅ Handle webhook verification (challenge-response)

Prepare Your Webhook Endpoint

Your webhook endpoint needs to handle two types of HTTP requests for the same URL path:

Why Two Methods?

Same URL, Different Purposes:

GET  https://your-server.com/webhooks/whatsapp  ← Verification

POST https://your-server.com/webhooks/whatsapp  ← Event notifications

1.1 Create a Webhook URL

Create a publicly accessible URL that can receive both GET and POST requests. This will be your webhook endpoint.

Good Examples:

https://your-server.com/webhooks/whatsapp

https://api.yourcompany.com/whatsapp/events

https://webhooks.yourapp.com/easysocial/whatsapp

Bad Examples:

http://localhost:3000/webhook (not public)

https://internal.company.com/webhook (not internet-accessible)

1.2 Implement Webhook Verification (GET Method)

Your endpoint must handle GET requests for verification. EasySocial will send a challenge that you must echo back.

What EasySocial Sends:

GET https://your-server.com/webhooks/whatsapp?verify_token=SECRET&challenge=abc123

Your Server Should Respond:

HTTP 200 OK

Content-Type: text/plain

abc123

Example Code (Node.js/Express):

app.get('/webhooks/whatsapp', (req, res) => {

  const verifyToken = req.query.verify_token;

  const challenge = req.query.challenge;

  // Echo back the challenge

  res.status(200).send(challenge);

});

Example Code (PHP):

<?php

$challenge = $_GET['challenge'];

// Echo back the challenge

http_response_code(200);

echo $challenge;

?>

Example Code (Python/Flask):

@app.route('/webhooks/whatsapp', methods=['GET'])

def verify_webhook():

    challenge = request.args.get('challenge')

    return challenge, 200

1.3 Handle Webhook Events (POST Method)

Your endpoint must accept POST requests with JSON payloads and respond with HTTP 200.

Example Code (Node.js/Express):

app.post('/webhooks/whatsapp', (req, res) => {

  const payload = req.body;

  // Process the webhook payload

  console.log('Received WhatsApp webhook:', payload);

  // Always respond with 200 OK within 4 seconds

  res.status(200).json({ status: 'ok' });

});

Example Code (PHP):

<?php

// Get the JSON payload

$payload = json_decode(file_get_contents('php://input'), true);

// Process the webhook payload

file_put_contents('webhook.log', json_encode($payload) . PHP_EOL, FILE_APPEND);

// Always respond with 200 OK

http_response_code(200);

echo json_encode(['status' => 'ok']);

?>

Example Code (Python/Flask):

@app.route('/webhooks/whatsapp', methods=['POST'])

def webhook_handler():

    payload = request.get_json()

    # Process the webhook payload

    print('Received WhatsApp webhook:', payload)

    # Always respond with 200 OK

    return {'status': 'ok'}, 200

1.4 Add Security (Recommended)

Verify webhook signatures to ensure requests come from EasySocial.

Example Code (Node.js):

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {

  const expectedSignature = crypto

    .createHmac('sha256', secret)

    .update(JSON.stringify(payload))

    .digest('hex');

  return signature === `sha256=${expectedSignature}`;

}

app.post('/webhooks/whatsapp', (req, res) => {

  const signature = req.headers['x-hub-signature-256'];

  const secret = 'YOUR_SECRET_TOKEN'; // Provided by EasySocial

  if (!verifySignature(req.body, signature, secret)) {

    return res.status(401).json({ error: 'Invalid signature' });

  }

  // Process webhook...

  res.status(200).json({ status: 'ok' });

});

1.5 Test Your Endpoint

Use these tools to test your webhook endpoint:

Using webhook.site (Easiest): 1. Go to https://webhook.site 2. Copy the generated URL 3. Test GET and POST requests to your endpoint

Using cURL:

# Test GET (verification)

curl "https://your-server.com/webhooks/whatsapp?verify_token=test&challenge=hello"

# Test POST (webhook event)

curl -X POST "https://your-server.com/webhooks/whatsapp" \

  -H "Content-Type: application/json" \

  -d '{"test": "data"}'

Next Steps

What Happens After You Prepare Your Endpoint

Once you've prepared your webhook endpoint:

1. Contact EasySocial Support with your webhook URL
2. Provide your verification token (if using custom verification)
3. EasySocial configures the webhook on their end
4. EasySocial subscribes to the events you need
5. You start receiving webhook notifications

EasySocial Handles

• ✅ Webhook registration in their system
• ✅ Event subscription management
• ✅ Security token management
• ✅ Webhook monitoring and retries
• ✅ Error handling and notifications

You Handle

• ✅ Webhook endpoint creation and maintenance
• ✅ Payload processing and business logic
• ✅ Server uptime and performance
• ✅ Error handling and logging

Testing Your Webhook

Local Development

Use ngrok to test locally:

# Install ngrok

npm install -g ngrok

# Start ngrok on your port

ngrok http 3000

# Use the ngrok URL as your webhook URL for testing

# Example: https://abc123.ngrok.io/webhooks/whatsapp

Sample Payloads

Incoming Message:

{

  "object": "whatsapp_business_account",

  "entry": [

    {

      "changes": [

        {

          "field": "messages",

          "value": {

            "contacts": [

              {

                "profile": { "name": "John Doe" },

                "wa_id": "1234567890"

              }

            ],

            "messages": [

              {

                "from": "1234567890",

                "id": "msg_123",

                "timestamp": "1640995200",

                "type": "text",

                "text": { "body": "Hello!" }

              }

            ]

          }

        }

      ],

      "es_id": 123,

      "timestamp": 1640995200000

    }

  ]

}

Message Status Update:

{

  "object": "whatsapp_business_account",

  "entry": [

    {

      "changes": [

        {

          "field": "message_status",

          "value": {

            "statuses": [

              {

                "id": "msg_123",

                "status": "delivered",

                "timestamp": "1640995260",

                "recipient_id": "1234567890"

              }

            ]

          }

        }

      ],

      "es_id": 123,

      "timestamp": 1640995260000

    }

  ]

}

Troubleshooting

Common Issues

Issue: "Endpoint not accessible"

Solution: - Ensure your server is publicly accessible - Check firewall settings - Verify HTTPS certificate is valid

Issue: "Verification failed"

Solution: - Make sure you're echoing the exact challenge value - Check for extra whitespace or encoding issues - Verify your GET endpoint is working

Issue: "Timeout errors"

Solution: - Ensure your server responds within 4 seconds - Check server performance and optimize if needed - Implement proper error handling

Issue: "Invalid signature"

Solution: - Verify you're using the correct secret token - Ensure you're hashing the raw JSON payload - Check for JSON formatting issues

Debugging Steps

1. Test with webhook.site:
   • Visit https://webhook.site
   • Use their URL to test your endpoint
   • Check request/response logs
2. Check Server Logs:
   • Look for incoming requests
   • Verify JSON parsing works
   • Check response times
3. Use cURL for Testing:

# Test verification

curl "https://your-endpoint.com/webhooks/whatsapp?challenge=test123"

# Test webhook payload

curl -X POST "https://your-endpoint.com/webhooks/whatsapp" \

  -H "Content-Type: application/json" \

  -d '{"test": "payload"}'

Support

Contact Information

Email: support@easysocial.io
Subject: WhatsApp Webhook Endpoint Setup
Response Time: < 24 hours

What to Include

When contacting support, please provide:

• Your webhook URL
• Programming language/framework used
• Error messages or issues encountered
• Server logs (if available)
• Test results from webhook.site or cURL

Quick Checklist

• [ ] Webhook URL is publicly accessible
• [ ] HTTPS certificate is valid
• [ ] GET requests return the challenge token
• [ ] POST requests return HTTP 200 within 4 seconds
• [ ] JSON payloads are properly parsed
• [ ] Server logs show successful processing

🎉 Great job! You've completed the integration partner portion of the WhatsApp webhook setup. Contact EasySocial support with your webhook URL to complete the configuration.

Need Help? Email support@easysocial.io with your webhook URL and any questions.