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
Step 1: Prepare a URL on your server
A public URL that accepts JSON
POSTrequests, such ashttps://example.com/hooks/whatsapp.localhostand private network addresses are refused. Your package needs the Webhooks feature.Step 2: Register it and keep the secret
Send
POST /webhookswithurland your keys. The response carries a 40-charactersecret; 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.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-Signatureheader. 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);Step 4: Answer fast, then process
Reply
200within 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:
| Event | When it arrives | Fields in `data` |
|---|---|---|
message.inbound | When a customer sends a text message to your linked number. | phone, text and handed_off (whether a chatbot rule handed it to staff) |
message.sent | When 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-Signatureon every request with a constant-time comparison such ashash_equalsortimingSafeEqual. - Keep the secret out of your code, in environment variables; if it leaks, register the URL again to get a new secret.
Common questions
message.inbound event carries the message text only. Incoming images and files show in WhatsApp on the linked phone.payload, sender and receiver. See the older platform section.Ready to start?
How to receive WhatsApp replies in your system by webhook

