Real-Time Event Stream

Webhooks & Event Listeners

Receive instant HTTP POST callbacks the exact moment shipment milestones change in the field.

Supported Event Types

Configure your server endpoint in the merchant portal to listen for specific milestone updates.

shipment.createdFired immediately after an airway bill is generated.

shipment.picked_upFired when the courier scans the package at merchant premises or hub.

shipment.in_transitFired during inter-city linehaul transitions and regional hub scans.

shipment.out_for_deliveryFired when package is loaded onto the courier van for final doorstep delivery.

shipment.deliveredFired when the customer signs and completes delivery with e-POD.

shipment.exceptionFired if address is incorrect or recipient is unavailable.

shipment.returnedFired if parcel is returned back to the merchant origin.

Sample Webhook Payload

Each callback payload includes an HMAC-SHA256 signature header for cryptographic verification.

Webhook Payload (JSON)

{
  "event": "shipment.delivered",
  "timestamp": "2026-09-01T15:45:00Z",
  "data": {
    "trackingNumber": "WASEL-8942-KSA",
    "referenceId": "ORDER-98124",
    "status": "DELIVERED",
    "deliveredAt": "2026-09-01T15:44:12Z",
    "recipient": "Sarah Al-Ghamdi",
    "ePod": {
      "signatureUrl": "https://api.stswasel.com/v1/epod/sig_99214.png",
      "photoUrl": "https://api.stswasel.com/v1/epod/photo_99214.jpg"
    }
  },
  "signature": "sha256=d3b07384d113edec49eaa6238ad5ff00"
}