The site is currently in beta.
WhatsApp API

How to receive WhatsApp replies in your system by webhook

Smart One Group support teamLast updated: 5 min read

Short answer

To receive your customers’ WhatsApp messages in your system, register a public HTTPS URL on your server with a POST to https://sog.sog.eg/api/whatsapp/webhooks and keep the secret it returns. Each customer reply then arrives as a message.inbound event and each outgoing message as message.sent, signed with the X-SOG-Signature header. Verify it with HMAC-SHA256 and answer 200 within 8 seconds.

On this page

Steps to connect the webhook

  1. Step 1: Prepare a URL on your server

    A public URL that accepts JSON POST requests, such as https://example.com/hooks/whatsapp. localhost and private network addresses are refused. Your package needs the Webhooks feature.

  2. Step 2: Register it and keep the secret

    Send POST /webhooks with url and your keys. The response carries a 40-character secret; store it in your server settings. Registering again replaces the URL and issues a new secret.

    curl -X POST https://sog.sog.eg/api/whatsapp/webhooks \
      -H "Accept: application/json" \
      -d appkey=YOUR_API_KEY -d authkey=YOUR_SECRET_KEY \
      -d url=https://example.com/hooks/whatsapp
    
    # → 200 {"data":{"url":"https://example.com/hooks/whatsapp",
    #        "secret":"Q2x8…40 characters…"}}
    # Store the secret on your server. Calling this again issues a new one.
  3. Step 3: Verify the signature on every request

    Compute HMAC-SHA256 of the request body exactly as received (before JSON parsing) with the secret and compare it with the X-SOG-Signature header. Reject anything that does not match.

    <?php
    $raw = file_get_contents('php://input');
    $expected = hash_hmac('sha256', $raw, getenv('SOG_WA_WEBHOOK_SECRET'));
    $given = $_SERVER['HTTP_X_SOG_SIGNATURE'] ?? '';
    
    if (! hash_equals($expected, $given)) {
        http_response_code(401);
        exit;
    }
    
    $event = json_decode($raw, true);
    // Queue $event for processing, then answer quickly.
    http_response_code(200);
  4. Step 4: Answer fast, then process

    Reply 200 within 8 seconds and handle the event afterwards, in a job queue for example. Each event is sent once.

Which events reach the webhook?

The event name comes in the body as event and in the X-SOG-Event header:

EventWhen it arrivesFields in `data`
message.inboundWhen a customer sends a text message to your linked number.phone, text and handed_off (whether a chatbot rule handed it to staff)
message.sentWhen a message leaves your number: from the API, a campaign, a schedule or an auto-reply.id, to, type and message_id
POST /hooks/whatsapp
Content-Type: application/json
X-SOG-Event: message.inbound
X-SOG-Signature: 5f2c…(HMAC-SHA256 hex)

{
  "event": "message.inbound",
  "data": {
    "phone": "201012345678",
    "text": "Is my order ready?",
    "handed_off": false
  }
}

What if my server was down and I missed an event?

The platform tries each event once and does not retry. To catch up, read the latest 100 incoming messages with GET /inbox, and the status of any message you sent with GET /messages/{id}, as in the WhatsApp API reference.

How do I secure the webhook URL?

  • Always use HTTPS and a URL that is hard to guess.
  • Check X-SOG-Signature on every request with a constant-time comparison such as hash_equals or timingSafeEqual.
  • Keep the secret out of your code, in environment variables; if it leaks, register the URL again to get a new secret.

Common questions

The message.inbound event carries the message text only. Incoming images and files show in WhatsApp on the linked phone.

No. There you set the webhook URL in the device settings, and requests arrive unsigned with payload, sender and receiver. See the older platform section.

Register a URL that answers 200 without processing, or open a support ticket to remove it from your account.

Ready to start?

How to receive WhatsApp replies in your system by webhook

Open my API keys