Webhooks

A webhook is a URL on your server that we POST to the moment something happens in the store. Set it when creating the key, later from Public API, or through the API (below).

#What we send

POST /your/webhook HTTP/1.1
Content-Type: application/json
X-Elmatajer-Event: order.created
X-Elmatajer-Event-Id: 6f1c0b8e-6b0a-4f9e-9d6c-2a7f2b1b5a10
X-Elmatajer-Signature: sha256=3b6c…

{
  "event": "order.created",
  "event_id": "6f1c0b8e-6b0a-4f9e-9d6c-2a7f2b1b5a10",
  "vendor_id": 5907,
  "created_at": "2026-11-03T18:00:16+02:00",
  "data": {
    "order": { "id": 4904, "order_number": "IOY539", "sub_total": 120, "tax": 0, "discount": 0, "grand_total": 150, "payment_type": 1, "status": 1 },
    "customer": { "id": null, "name": "Mona Adel", "email": "mona@example.com", "phone": "+201012345678" }
  }
}

order.status_changed carries order_id, order_number, from_status, to_status and customer. Fetch the full order with Get an order when you need its items.

#Verify the signature

X-Elmatajer-Signature is sha256= + HMAC-SHA256 of the raw body with the key's webhook secret. Compare in constant time; reject anything that doesn't match.

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_ELMATAJER_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}
$event = json_decode($raw, true);
http_response_code(200);

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Elmatajer-Signature') || ''));

#Delivery and retries

• Answer any 2xx within 12 seconds. Anything else is retried after 1, 5, 15, 60 and 180 minutes (up to 8 attempts).
• Delivery is at least once — use X-Elmatajer-Event-Id to ignore a repeat.
• Events of one order arrive in order.
• Public API → Send a test event posts a webhook.test event so you can check your endpoint.

#Manage it from the API

All three need the webhooks permission. The URL must be https on a public host.