Push Mechanism

1. Push Mechanism

Subscribing to Omisell Push Mechanism helps you get immediate notifications when a specific event occurs. This lets you receive timely updates without having to periodically poll the API endpoint.

NOTE

Push Mechanism on the Omisell Platform Console is equivalent to what's commonly known as webhooks.

Here's an overview of how Push Mechanism works on Omisell Open Platform:

You subscribe to a specific push type for your platform and define a callback URL.

The specific event, such as an order status update, happens.

Omisell sends an HTTP POST request to the defined callback URL.

You receive a notification via your defined callback URL.

INFO

Push Mechanism (webhooks) on Omisell Platform only notifies you that data for the specific event has changed. To get more updated information, make a call to the corresponding API. You're encouraged to use both to enhance your systems' integration efficiency.

2. Events

2.1. Order Status Push

Event	Event name	Description
`order.created`	Order - Created	⚠️ Fires when the order reaches 300 Approved, NOT when the order is created. An order created through `POST /order/add` without `approve: true` stays at `200 New` and never receives this event.
`order.processing`	Order - Processing	Push when the order has been created for shipment
`order.update_serial`	Order - Update Lot/Serial	Push when order has change Lot/Serial number during packing
`order.ready_to_ship`	Order - Ready to Ship	Push when the order is ready to ship
`order.shipped`	Order - Shipped	Push when the order has been handed over to the shipping carrier
`order.partially_completed`	Order - Partially Completed	Push when one package of a multi-package order is completed
`order.completed`	Order - Completed	Push when the order is completed
`order.returned`	Order - Returned	Push when order status is Returned
`order.cancelled`	Order - Cancelled	Push when order status is Cancelled
`order.reconciled`	Order - Reconciled	Push when order status is Reconciled
`order.return_receive`	Order - Return Receive	Push when the order is return receive at the warehouse
`order.exceptions`	Order - Exceptions	Push when the order is Exceptions
`order.courier_lost_items`	Order - Courier lost items	Push when the order is Courier lost items

2.2. Shipment (DO) Status Push

Event	Event name	Description
`shipment.created`	Shipment - Created	Push when the shipment has been successfully created
`shipment.ready_to_ship`	Shipment - Ready to Ship	Push when shipment status is RTS
`shipment.shipped`	Shipment - Shipped	Push when shipment status is Shipped
`shipment.delivery_failure`	Shipment - Failed Delivery Attempt	Push when shipment status is Failed Delivery Attempt
`shipment.delivered`	Shipment - Delivered	⚠️ Fires for both `800 Delivered` and `317 Courier lost items`. Do not mark a delivery successful on this event alone — read `data.status_id` to tell them apart.
`shipment.returned`	Shipment - Returned	Push when shipment status is Returned
`shipment.cancelled`	Shipment - Cancelled	Push when shipment status is Cancelled
`shipment.exceptions`	Shipment - Exceptions	Push when shipment status is Exceptions

2.3. Returns Order Push

Event	Event name	Description
`order_return.requested`	Return Order - Requested	Push when the return order is requested
`order_return.accepted`	Return Order - Accepted	Push when the return order is accepted
`order_return.processing`	Return Order - Processing	Push when the return order is processing
`order_return.refund_paid`	Return Order - Returned	Push when the return order is refund paid
`order_return.closed`	Return Order - Closed	⚠️ Subscribable but never fires: no return-order status maps to this event.
`order_return.cancelled`	Return Order - Cancelled	Push when the return order is cancelled

2.4. Payload format

Every subscription carries a format. The default is cus, and the payload documented under Webhooks in the API reference is that format:

{ "data": { …object summary… }, "shop_id": …, "seller_id": …, "platform": …, "event": …, "timestamp": …, "request_id": … }

WARNING

A subscription created with a different format receives a different, much larger payload for the same event. If your subscription was set up by Omisell for an ERP integration, confirm the format before coding against the examples.

3. How to Set Up Webhook

3.1. Add Hook

3.2. Monitoring API Call & Push Log

3.4. Push Authorization

To prevent cyberattacks, we have provided an authorization signature for each Push request, which can be located in the Authorization field of the HTTP request header. With this, you can identify Omisell's authorization information.

This step is technically optional, but we strongly recommend that developers validate the request by generating the authorization signature and ensuring it matches the one from the Push request.

Example of Omisell's request headers:

4. Retry Schedule

If a delivery fails, Omisell retries with an increasing delay. ⚠️ The schedule below applies to most events, except order.processing and shipment.created — those two go through a separate tracking mechanism (a retry × 1 hour window, capped at 3 attempts) instead of this backoff schedule.

Attempt	Countdown (Seconds)	Human Readable Delay
1st Retry	300s	5 minutes
2nd Retry	600s	10 minutes
3rd Retry	1,200s	20 minutes
4th Retry	2,400s	40 minutes
5th Retry	4,800s	1 hour 20 minutes

5. Webhook Delivery Monitoring & Auto-Disable

To keep webhook delivery reliable, our system continuously monitors the success rate of deliveries to your endpoint.

5.1. How It's Measured

We look at deliveries over the last 6 hours.

Success = your endpoint returns an HTTP 2xx status (200, 201, …).

Failure = a 4xx/5xx status, or the endpoint is unreachable (timeout/no response).

Success rate = successful deliveries / total deliveries.

We only evaluate once there is enough data: at least 40 deliveries in the 6-hour window. Below this, no warning or disable is triggered (to avoid judging on too small a sample).

5.2. Warning

WARNING

When the success rate drops below 70%, a warning is recorded (at most once every 30 minutes). The warning clears automatically once the success rate returns to 70% or above.

5.3. Disable

DANGER

When the success rate drops below 30%, your webhook subscription will be disabled.

Please check your endpoint (callback URL) and make sure it can receive webhooks normally before re-enabling.

The system does not re-enable automatically — you need to re-activate the subscription yourself after fixing the issue.

5.4. Monitoring Status

You can view your webhook health (success rate, total deliveries, response codes) in the webhook list on the management portal.

1. Push Mechanism#

2. Events#

2.1. Order Status Push#

2.2. Shipment (DO) Status Push#

2.3. Returns Order Push#

2.4. Payload format#

3. How to Set Up Webhook#

3.1. Add Hook#

3.2. Monitoring API Call & Push Log#

3.4. Push Authorization#

4. Retry Schedule#

5. Webhook Delivery Monitoring & Auto-Disable#

5.1. How It's Measured#

5.2. Warning#

5.3. Disable#

5.4. Monitoring Status#

1. Push Mechanism

2. Events

2.1. Order Status Push

2.2. Shipment (DO) Status Push

2.3. Returns Order Push

2.4. Payload format

3. How to Set Up Webhook

3.1. Add Hook

3.2. Monitoring API Call & Push Log

3.4. Push Authorization

4. Retry Schedule

5. Webhook Delivery Monitoring & Auto-Disable

5.1. How It's Measured

5.2. Warning

5.3. Disable

5.4. Monitoring Status