Using webhooks

Introduction to Webhooks

Webhooks allow your application to receive real-time notifications about payloads happening in your WhatsApp sessions. With WasenderApi webhooks, you can build interactive applications that respond to message delivery status, incoming messages, session status changes, and more.

Enabling Webhooks

You can enable webhooks when creating a new WhatsApp session or by updating an existing session:

Setting Up Your Webhook Endpoint

Your webhook endpoint should be a publicly accessible URL that can receive POST requests. Here's an example implementation using Express.js:

// Example webhook endpoint in Express.js
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Verify webhook signature to ensure it's from WasenderApi
function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const webhookSecret = 'YOUR_WEBHOOK_SECRET'; // Store securely in environment variables
  if (!signature || !webhookSecret) return false;
  if(signature !== webhookSecret) return false;
  return true;
}

app.post('/webhook', (req, res) => {
  // Verify the request is from WasenderApi
  if (!verifySignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook payload
  const payload = req.body;
  console.log('Received webhook payload:', payload.event);

  // Handle different payload events
  switch(payload.event) {
    case 'message.sent':
      console.log('Message sent:', payload.data.id);
      break;
    case 'session.status':
      console.log('Session status changed to:', payload.data.status);
      break;
    case 'messages.upsert':
      console.log('New message received:', payload.data.key.id);
      break;
    case 'messages.update':
      console.log('Message updated:', payload.data.key.id);
      break;
    case 'messages.delete':
      console.log('Message deleted:', payload.data.key.id);
      break;
    case 'message-receipt.update':
      console.log('Message receipt updated:', payload.data.key.id);
      break;
    case 'messages.reaction':
      console.log('Message reaction:', payload.data.key.id);
      break;
    case 'chats.upsert':
      console.log('New chat created:', payload.data.id);
      break;
    case 'chats.update':
      console.log('Chat updated:', payload.data.id);
      break;
    case 'chats.delete':
      console.log('Chat deleted:', payload.data.id);
      break;
    case 'groups.upsert':
      console.log('New group created:', payload.data.id);
      break;
    case 'groups.update':
      console.log('Group updated:', payload.data.id);
      break;
    case 'group-participants.update':
      console.log('Group participants updated:', payload.data.id);
      break;
    case 'contacts.upsert':
      console.log('New contact added:', payload.data.id);
      break;
    case 'contacts.update':
      console.log('Contact updated:', payload.data.id);
      break;
  }

  // Always respond with 200 OK to acknowledge receipt
  res.status(200).json({ received: true });
});

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

Webhook Security

To ensure that webhook requests are genuinely from WasenderApi, we include a signature header with each request. You should verify this signature before processing the webhook data:

• X-Webhook-Signature: A signature that you can verify using your webhook secret

When you enable webhooks, a webhook secret is automatically generated for your session. You can view this secret in your session management screen. Always store this secret securely and never expose it in client-side code.

Webhook payload Format

Here's an example of a webhook payload for a sent message:

{
  "event": "message.sent",
  "timestamp": 1633456789,
  "data": {
    "id": "message-id-123",
    "to": "+1234567890",
    "status": "sent",
    "type": "text",
    "content": "Hello from WasenderApi!"
  }
}

And here's an example of a session status change payload:

{
  "event": "session.status",
  "timestamp": 1633456789,
  "data": {
    "status": "connected", // or "disconnected", "need_scan"
    "session_id": "your session api_key"
  }
}

Best Practices

• Respond quickly: Your webhook endpoint should respond with a 200 status code as quickly as possible
• Process asynchronously: Handle time-consuming operations asynchronously after responding to the webhook
• Implement retry logic: Be prepared to handle temporary failures in your webhook processing
• Monitor webhook deliveries: Set up logging to track webhook deliveries and processing
• Secure your endpoint: Always verify the webhook signature and use HTTPS for your endpoint

Troubleshooting