Webhook Endpoint Details Guide

This document explains how to create, validate, and consume webhook events using a single HTTPS endpoint that supports both GET and POST methods.

Overview

• One endpoint for webhook integration
• Two HTTP methods on the same URL
• GET → Webhook validation
• POST → Webhook events
• Secure event delivery using HMAC signature verification

Example webhook URL:

https://example.app/webhook

Step 1: Create a Webhook Endpoint

You must create one endpoint that handles both GET and POST requests.

Route Structure

• GET /webhook → Used for webhook validation
• POST /webhook → Used for receiving webhook events

Mandatory Requirements

• Must be accessible over HTTPS
• GET and POST must be on the same endpoint
• Logic must be separated by HTTP method
• Must always return 200 OK for valid requests

Step 2: Register Webhook in Dashboard

When configuring the webhook in the dashboard:

1. Enter Webhook URL https://example.app/webhook

2. Enter Secret Key

   • Used to sign webhook payloads
   • Must be stored securely on your server

3. Select Events

   • incoming_message – Receive all incoming messages
   • status_update – Receive message delivery status updates

4. Click Register

Step 3: Webhook URL Validation (GET Request)

When you save the webhook URL, the system sends a GET request with a challenge query parameter.

Incoming Request

GET /webhook?challenge=abc123

Expected Client Behavior (Your Code)

• Read the challenge from query parameters
• Respond with the exact same value
• Response must be JSON
• HTTP status must be 200 OK

Expected Response

{
  "challenge": "abc123"
}

If the response does not match exactly, webhook registration will fail.

Step 4: Handle Webhook Events (POST Request)

After successful validation, your endpoint will start receiving POST requests for the subscribed events.

POST Request Headers

Each webhook event will be sent with the following headers:

const headers = {
  "Content-Type": "application/json",
  "X-Wappcloud-Event": eventType,
  "X-Wappcloud-Signature": `sha256=${signature}`,
};

Header Description

POST Request Body

JSON payload

• Structure depends on the event type
• Must be parsed as JSON

Signature Verification (Strongly Recommended)

To verify request authenticity:

1. Read X-Wappcloud-Signature header
2. Generate HMAC SHA256 using your secret key and request body
3. Compare it with the received signature
4. Reject the request if signatures do not match

Expected Server Behavior Summary