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 create	Push new order
`order.ready_to_ship`	Order RTS	Push when order status is RTS
`order.shipped`	Order Shipped	Push when order status is Shipped
`order.completed`	Order Completed	Push when order status 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`	Returns Order Received	Push when returns order already received & restock at warehouse

2.2. Shipment (DO) Status Push

Event	Event name	Description
`shipment.created`	Shipment create	Push new shipment
`shipment.ready_to_ship`	Shipment RTS	Push when shipment status is RTS
`shipment.shipped`	Shipment Shipped	Push when shipment status is Shipped
`shipment.delivered`	Shipment Delivered	Push when shipment status is Delivered
`shipment.returned`	Shipment Returned	Push when shipment status is Returned
`shipment.cancelled`	Shipment Cancelled	Push when shipment status is Cancelled

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	Push when the return order is closed
`order_return.cancelled`	Return Order - Cancelled	Push when the return order is cancelled

3. How to Set Up Webhook

3.1. Setting Webhook

3.2. Add Hook

3.3. 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 following table illustrates the delay duration for each retry attempt:

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#

3. How to Set Up Webhook#

3.1. Setting Webhook#

3.2. Add Hook#

3.3. 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

3. How to Set Up Webhook

3.1. Setting Webhook

3.2. Add Hook

3.3. 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