Outbound events

Noukarivé webhooks

Receive signed logistics events from Noukarivé without polling the API. Endpoint secrets are displayed once and can be rotated from the account automation area.

HTTP request & payload

Noukarivé sends an HTTP POST with a raw JSON body and these headers:

Content-Type: application/json X-Noukarive-Event: shipment.updated X-Noukarive-Event-Id: 5de5c...uuid... X-Noukarive-Signature: sha256=HEX_HMAC

Envelope:

{ "event": "shipment.updated", "data": { "shipment_id": 123, "tracking_code": "NKR-...", "status": "in_transit" }, "occurred_at": "2026-08-13T22:00:00+00:00" }

Treat X-Noukarive-Event-Id as the delivery event’s idempotency key on your side. Store processed event IDs and return 2xx for duplicate deliveries without applying the business action twice.

Verify the signature

The signature is an HMAC-SHA256 of the exact raw request body, using the endpoint signing secret.

$rawBody = file_get_contents('php://input'); $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret); $received = $_SERVER['HTTP_X_NOUKARIVE_SIGNATURE'] ?? ''; if (! hash_equals($expected, $received)) { http_response_code(401); exit; }

Important: verify the signature before decoding or re-serializing JSON. Any change in whitespace or key serialization changes the HMAC.

Retries & delivery contract

A delivery is successful on any HTTP 2xx response. Noukarivé uses a 10-second request timeout and up to five attempts with the following queue backoff:

60 s5 min30 min2 h6 h

Respond quickly, persist the event, then process asynchronously on your side. Endpoint failures and delivery history are visible in the account integration area.

Business webhook events

Event	Current status	Purpose
`order.created`	Emitted	Business API order was created.
`order.accepted`	Reserved/selectable	Event name is accepted by endpoint configuration but is not yet emitted end-to-end in the current codebase.
`shipment.started`	Reserved/selectable	Reserved for business shipment lifecycle.
`shipment.updated`	Reserved/selectable	Reserved for business shipment lifecycle.
`shipment.delivered`	Reserved/selectable	Reserved for business shipment lifecycle.