WebhooksOverview & subscriptions

Webhooks — overview & subscriptions

Webhooks are how you learn about changes. Given the current limits on order list filtering, they are the primary integration mechanism for order intake, not an optimisation.

Endpoint	Description
GET /webhooks	List your app's subscriptions
POST /webhooks	Create a subscription — returns 201
GET /webhooks/{id}	Get one subscription
PUT /webhooks/{id}	Update a subscription
DELETE /webhooks/{id}	Delete a subscription
POST /webhooks/test	Send a synthetic event to an active subscription — returns 202

Creating a subscription

One event type per subscription. eventType is a single value, not a list — to receive five event types, create five subscriptions.

POST /open/v1/webhooks
{
  "eventType":   "order.created",
  "callbackUrl": "https://api.yourcompany.com/hooks/mallplus"
}

Both fields are required, and the body is strict — any other field is rejected with 400 VALIDATION_ERROR. eventType must be one of the values in the event catalog.

Updating a subscription

PUT /open/v1/webhooks/{id}
{
  "callbackUrl": "https://api.yourcompany.com/hooks/mallplus-v2",  // optional
  "isActive":    false                                            // optional — pause without deleting
}

The event type is fixed at creation. To change it, delete the subscription and create a new one.

Callback URL requirements

Must be https:// in production, and publicly resolvable.
Private, loopback, link-local, carrier-NAT and cloud-metadata addresses are rejected at subscribe time with 400 VALIDATION_ERROR. The hostname is re-resolved and re-checked at delivery time, so a domain that later starts resolving to a private address stops receiving deliveries.
If the hostname cannot be resolved, the delivery is not attempted.
At most one redirect is followed, and the redirect target is re-validated.
Respond within 10 seconds. Acknowledge first, process asynchronously.