The store's webhooks: receive new orders in your system and verify the signature
The developer guide to the ArabyBot store's webhooks: the two events order.created and order.updated, the headers, how to verify the signature with an example, the body's shape, and the retry schedule.
On this page 7
The short answer
With the store's webhooks: in the store settings you add an address on your server that starts with https, and ArabyBot sends it a signed POST request when every order is created and on each update to it. The body carries the event's name and the whole order in the same shape the store API returns. If your server does not answer with success, the attempt is repeated five times at intervals that grow from one minute to six hours.
Also asked as: «الطلب الجديد يوصل السيستم بتاعي لوحده ازاي» · «ويب هوك المتجر» · «التحقق من توقيع webhook» · «order created webhook» · «how to verify a webhook signature»
Your address and the signature
POST https://your-server.example/arabybot-webhook
There is no key here: ArabyBot is the one sending to your address, so you check that the request is ours. Every notification carries the header X-ArabyBot-Signature, whose value is sha256= followed by an HMAC-SHA256 with the address's secret over «the timestamp, a dot, then the request body», with the timestamp in the header X-ArabyBot-Timestamp. Refuse any timestamp older than five minutes.
The headers you receive
X-ArabyBot-Event(required) The event's name:order.createdororder.updated.X-ArabyBot-Delivery(required) This notification's id; it stays the same on a retry, so use it to avoid processing twice.X-ArabyBot-Timestamp(required) The time of sending in seconds (unix time).X-ArabyBot-Signature(required) The signature:sha256=then an HMAC-SHA256 with the secret over «timestamp.body».
Verifying the signature
PHP
// PHP: verify before trusting the body
$secret = getenv('ARABYBOT_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_ARABYBOT_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_ARABYBOT_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (abs(time() - (int) $ts) > 300 || ! hash_equals($expected, $sig)) {
http_response_code(401);
exit;
}
$event = json_decode($body, true); // $event['event'], $event['order']
http_response_code(200); Node.js (Express)
const crypto = require('crypto');
app.post('/arabybot-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-ArabyBot-Timestamp') || '';
const sig = req.get('X-ArabyBot-Signature') || '';
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.ARABYBOT_WEBHOOK_SECRET)
.update(ts + '.' + req.body).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const same = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!fresh || !same) return res.sendStatus(401);
const event = JSON.parse(req.body); // event.event, event.order
res.sendStatus(200);
}); Python (Flask)
import hashlib, hmac, os, time
from flask import Flask, request
app = Flask(__name__)
@app.post('/arabybot-webhook')
def hook():
ts = request.headers.get('X-ArabyBot-Timestamp', '')
sig = request.headers.get('X-ArabyBot-Signature', '')
body = request.get_data()
expected = 'sha256=' + hmac.new(os.environ['ARABYBOT_WEBHOOK_SECRET'].encode(), ts.encode() + b'.' + body, hashlib.sha256).hexdigest()
if not ts.isdigit() or abs(time.time() - int(ts)) > 300 or not hmac.compare_digest(expected, sig):
return '', 401
event = request.get_json() # event['event'], event['order']
return '', 200
What arrives in the body
{ "event": "order.created", "store_id": 12, "sent_at": "2026-11-16T18:04:11+00:00",
"order": {
"id": 9041, "number": "1042", "status": "confirmed", "cancel_reason": null,
"payment_method": "cod", "payment_status": "…", "currency": "EGP",
"subtotal": 480.0, "discount": 0.0, "shipping": 50.0, "fee": 0.0, "vat": 0.0,
"total": 530.0, "refunded": 0.0, "coupon": null, "note": null, "tags": null,
"customer": { "name": "…", "phone": "+2010XXXXXXXX" },
"shipping_address": { "country": "EG", "region": "…", "city": "…", "address": "…", "pickup": false },
"gift": null, "delivery_slot": null,
"tracking": { "carrier": null, "number": null, "url": null },
"source": { "utm_source": null, "utm_campaign": null, "ref": null },
"items": [ { "product_id": 88, "variant_id": 301, "name": "…", "variant": "…", "sku": "…",
"qty": 2, "returned_qty": 0, "unit_price": 240.0, "line_total": 480.0, "uploads": [] } ],
"created_at": "2026-11-16 18:04:10", "confirmed_at": "2026-11-16 18:20:02",
"shipped_at": null, "delivered_at": null
} } orderhas the same shape the store API returns, so you write its parsing once.- Answer with a 2xx status quickly, and leave long processing until after the response.
- A store can have up to three addresses, and each must be https on a public server.
Retries on failure
Any response from your server that is not 2xx counts as a failure, and the same notification is sent again with the same id:
- 2: The second attempt after one minute.
- 3: The third after five minutes.
- 4: The fourth after thirty minutes.
- 5: The fifth after two hours.
- 6: The sixth after six hours; if it fails too, the notification is marked failed.
The limits
The notification is written to an outbox the moment the event happens and then sent, so it never delays checkout in the store. Notifications go out every minute, up to twenty per address in one run.
All store API addresses · All APIs for developers
Frequently asked questions
How do I make sure the notification is from ArabyBot and not someone else?
Compute the signature with your address's secret over «the timestamp, a dot, the raw body» and compare it with the X-ArabyBot-Signature header using a safe comparison, and refuse a timestamp older than five minutes. The example on this page does that.
What happens if my server was down when the notification arrived?
It is sent again five times at growing intervals: one minute, then five minutes, then thirty minutes, then two hours, then six hours. With the notification id in the header you avoid processing it twice.
Read next
Try the agent before you pay anything
The agent that will answer your customers is the one answering you now: ask it from the chat button here or on WhatsApp. Your account is free with no credit card, and the free trial on your own number or page is activated after you contact our team on customer-service WhatsApp.