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 slugWhen it fires
order-createImmediately after a new order is saved to your account.
order-updateWhenever any order field is updated.
order-status-changedWhen the order status changes (in addition to order-update).
order-deleteWhen an order is soft-deleted.
3

HTTP request

MethodPOST, PUT, or PATCH (configured per webhook)
Content-Typeapplication/json
User-AgentWingezz-Webhooks/1.0
TimeoutWingezz waits up to 20 seconds for your server to respond.
Request headers
HeaderDescription
X-Wingezz-Hmac-Sha256Base64-encoded HMAC-SHA256 of the raw request body using your webhook signing secret.
X-Wingezz-EventEvent slug (e.g. order-create).
X-Wingezz-Webhook-IdYour webhook configuration ID.
X-Wingezz-Delivery-IdUnique 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.