Webhooks

Receiver-ready, dispatch not yet live

The contract below — event names, payload shape, and HMAC signature scheme — is what the official WooCommerce plugin already implements and verifies on its receiving end. The Boyasa API does not yet send these events; there is no outbound webhook dispatcher implemented server-side. If you're integrating today, poll GET /packages/:id for status changes instead.

Event types

Event	Fired when
delivery.assigned	A driver/rider is assigned to the order
delivery.picked_up	The driver has picked up the package
delivery.in_transit	The driver has started the delivery
delivery.delivered	The package has been delivered
delivery.failed	The delivery attempt failed
delivery.cancelled	The order was cancelled

Payload

POST https://your-site.com/wp-json/boyasa/v1/webhook

{
  "event": "delivery.delivered",
  "delivery_id": "ord_9f8c2b1a",
  "status": "DELIVERED",
  "timestamp": "2026-07-06T21:32:00Z"
}

Verifying the signature

Every request is signed with HMAC-SHA256 using your webhook secret, sent in the X-Boyasa-Signature header:

PHP

$expected = hash_hmac('sha256', $raw_request_body, $webhook_secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_BOYASA_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}