Webhook Model V1

Outgoing event envelope, supported event types and signature verification.

Event Envelope

Signed webhook notification

Bulbulustur sends an HTTP POST with a JSON envelope containing id, type, storeId, createdAt, and data. Event identifiers: order.created, order.updated, return.created, return.updated. Use * to subscribe to all types.

Payload data depends on the event publisher. Automatic production delivery requires event publication from the order/return workflows; registering a subscription alone does not activate an event producer.

Signature and Delivery

HMAC-SHA256 verification

Headers: X-Bulbulustur-Event, X-Bulbulustur-Delivery, and X-Bulbulustur-Signature. The signature header is t=timestamp,v1=hex_hmac. Compute HMAC-SHA256 over UTF-8 timestamp + "." + rawBody with the signing secret from the subscription creation response.

Verify the raw request body using a constant-time comparison, reject stale timestamps, and deduplicate by delivery ID. Delivery retries up to three times. Ten consecutive failures disable the subscription; a 2xx response is successful.