Webhook Documentation

Receive real-time signed HTTP notifications when order events occur in your Wingezz account.

Real-time Events

HMAC Signature Verification

Custom Body Mapping

العربية English API Documentation

Integration Guide

Connect your server to Wingezz webhooks and process order events securely.

1

Overview

Wingezz webhooks let your system receive real-time HTTP notifications when order events happen in your account. Register a URL for each event type; we send a signed request with order data.

  1. Add a webhook URL and select an action (e.g. order-create).
  2. Copy the signing secret shown once — store it securely on your server.
  3. When the event occurs, Wingezz sends JSON to your URL with HMAC headers.
  4. Verify the signature, then process the order data.
  5. Return HTTP 2xx quickly; use Webhook Logs to debug deliveries.
2

Available events

Event slug When it fires
order-create Immediately after a new order is saved to your account.
order-update Whenever any order field is updated.
order-status-changed When the order status changes (in addition to order-update).
order-delete When an order is soft-deleted.
3

HTTP request

Method POST, PUT, or PATCH (configured per webhook)
Content-Type application/json
User-Agent Wingezz-Webhooks/1.0
Timeout Wingezz waits up to 20 seconds for your server to respond.
Request headers
Header Description
X-Wingezz-Hmac-Sha256 Base64-encoded HMAC-SHA256 of the raw request body using your webhook signing secret.
X-Wingezz-Event Event slug (e.g. order-create).
X-Wingezz-Webhook-Id Your webhook configuration ID.
X-Wingezz-Delivery-Id Unique ID for this delivery attempt.
4

Verifying signatures

Compute HMAC-SHA256 of the raw request body with your signing secret, then base64-encode the result. Compare with the X-Wingezz-Hmac-Sha256 header using a timing-safe comparison. 

// PHP example
$secret = 'your_webhook_signing_secret';
$rawBody = file_get_contents('php://input');
$expected = base64_encode(hash_hmac('sha256', $rawBody, $secret, true));
$provided = $_SERVER['HTTP_X_WINGEZZ_HMAC_SHA256'] ?? '';
if (!hash_equals($expected, $provided)) {
 http_response_code(401);
 exit('Invalid signature');
}
5

Default payload example

If you do not configure a custom body mapping, the full default payload is sent: 

{
 "event": "order-create",
 "sent_at": "2026-09-02T10:30:00+03:00",
 "order": {
 "id": 12345,
 "serial_no": "WNG-12345",
 "reference_no": "REF-001",
 "type": "Delivery",
 "status": "جديد",
 "status_en": "New",
 "customer_name": "Ahmed",
 "customer_phone": "201012345678",
 "govern": "Cairo",
 "area": "Nasr City",
 "cost": 150,
 "deliver_cost": 30,
 "source": "api",
 "created_at": "2026-09-02T10:00:00+03:00"
 }
}
6

Custom body mapping

You can define your own JSON keys and map them to order fields. Foreign keys are resolved to human-readable values (status name instead of status ID, governorate name instead of govern_id, etc.). Internal IDs and sensitive fields are never exposed.

You can also add custom HTTP headers (e.g. Authorization or X-Api-Key) from the webhook settings page. Wingezz signing headers are always set automatically and cannot be overridden.

Manage webhooks from your Wingezz dashboard under Webhooks, or from your trader profile settings.

Security notes

  • Always verify the HMAC signature before processing webhook data.
  • Webhooks only include data from orders belonging to your trader account.
  • Only whitelisted order fields can be included in custom payloads.
  • Store your signing secret securely; regenerate it if compromised.
  • Webhook URLs must use HTTPS and cannot target private networks or cloud metadata endpoints.