The store API

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.

5 min read Updated 16 November 2026 ArabyBot team
The ArabyBot teamOfficial Meta partner · written from our own platform data
On this page 7
  1. Your address and the signature
  2. The headers you receive
  3. Verifying the signature
  4. What arrives in the body
  5. Retries on failure
  6. The limits
  7. Frequently asked questions

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.created or order.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
  } }
  • order has 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.
ArabyBot's API as it runs today, read from the system itselfmeasured 16 November 2026

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

1

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.

2

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.

The ArabyBot teamOfficial Meta business partner in the Middle East 264 guides Figures from our platform All guides

How we write these guides Figures come from our platform and Meta's actual invoices, dated with their sample; we describe what works today, not what we plan, and say what we do not do and when someone else is the better choice. Reviewed by the ArabyBot team on 16 November 2026.

Share this guide

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.

And you run all of it from your phoneEverything on this page is also run from the ArabyBot mobile app — replies, orders, campaigns and AI reports. Not a web dashboard only.