Webhook Setup API Documentation

Module: Webhook Setup

Base URL: /api/webhooks

1. Overview

The Webhook API enables applications to receive real-time updates for specific WhatsApp sessions, including incoming messages, message status changes (sent, delivered, read), and media events.

Key features:

• Create or update a webhook per session

• Retrieve webhook configuration

• Delete webhooks

• Support multiple events per webhook

2. Endpoints

2.1 Set or Update Webhook

Endpoint: POST /api/webhooks/set

Description: Create a new webhook for a session or update an existing one.

Request Body (JSON):

{
  "sessionId": "string",       // Unique WhatsApp session ID
  "webhookUrl": "string",      // Destination URL for webhook events
  "events": ["string"]         // List of events to subscribe to
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "_id": "642f8b9c5c0f8a1b2c3d4e5f",
    "sessionId": "session123",
    "webhookUrl": "https://example.com/webhook",
    "events": ["message_received", "message_sent"],
    "createdAt": "2025-10-09T10:45:00.000Z",
    "updatedAt": "2025-10-09T10:45:00.000Z"
  }
}

Error Responses:

• 400 Bad Request

{
  "success": false,
  "message": "Missing or invalid fields"
}

• 500 Server Error

{
  "success": false,
  "message": "Failed to set webhook"
}

2.2 Get Webhook by Session ID

Endpoint: GET /api/webhooks/:sessionId

Description: Retrieve webhook configuration for a given WhatsApp session.

URL Parameters:

• sessionId (string, required) – WhatsApp session ID

Success Response (200 OK):

{
  "success": true,
  "data": {
    "_id": "642f8b9c5c0f8a1b2c3d4e5f",
    "sessionId": "session123",
    "webhookUrl": "https://example.com/webhook",
    "events": ["message_received", "message_sent"],
    "createdAt": "2025-10-09T10:45:00.000Z",
    "updatedAt": "2025-10-09T10:45:00.000Z"
  }
}

Error Responses:

• 404 Not Found

{
  "success": false,
  "message": "Webhook not found"
}

• 500 Server Error

{
  "success": false,
  "message": "Server error"
}

2.3 Delete Webhook

Endpoint: DELETE /api/webhooks/:sessionId

Description: Delete a webhook for a specific session.

URL Parameters:

• sessionId (string, required) – WhatsApp session ID

Success Response (200 OK):

{
  "success": true,
  "message": "Webhook deleted",
  "data": {
    "_id": "642f8b9c5c0f8a1b2c3d4e5f",
    "sessionId": "session123",
    "webhookUrl": "https://example.com/webhook",
    "events": ["message_received", "message_sent"],
    "createdAt": "2025-10-09T10:45:00.000Z",
    "updatedAt": "2025-10-09T10:45:00.000Z"
  }
}

Error Responses:

• 500 Server Error

{
  "success": false,
  "message": "Failed to delete webhook"
}

3. Events

4. Notes & Recommendations

• Use HTTPS URLs for webhook URLs to ensure security.

• Webhooks are upserted: a new one is created if sessionId does not exist; otherwise, it is updated.

• Always check the response for success: true to ensure proper setup.

• Timestamps (createdAt, updatedAt) help track webhook changes.