Webhook Overview

This specification describes how AfterShip Returns Center sends webhook events. You can implement your webhook callback endpoint accordingly.

When a "return" is created or updated in the Returns Center (i.e. a customer has submitted a return request), the system will emit a corresponding event by sending an HTTP POST payload to the webhook's configured URL. (Updates include only the returns of your own connected stores in AfterShip Returns Center).

Please check out the detailed payload on this page.


Currently, we only support this feature upon request. Please contact [email protected] for an integration request. We will need you to provide an HTTPS URL, and we will integrate this into our webhook delivery destinations.

After registration, we will provide a webhook secret for you to verify our webhook delivery.

We currently support either HTTP or HTTPS URLs, so you can have security by using an SSL-enabled URL. But keep in mind that your endpoint is going to be wide-open on the Internet, and you might not want others to be able to submit random data to your systems. At this time, please aside from trying to keep the URL private. We advise you to simply include a secret key in the URL that you can use to check the secret GET parameter in your scripts.

Retry Webhooks

The webhook receiver shall respond with a 2xx status code. In case of an unsuccessful event (HTTP response code NOT between 200 and 299), AfterShip attempts to deliver your webhooks up to 14 times with exponential backoff.

The attempted webhook delay is calculated by this formula:

2^(number of retries) x 30 seconds

# of attempt# of retryDelay (sec) before send outAcc. Delay (sec)
1000
213030
326090
43120210
54240450
65480930
769601890
8719203810
9838407650
109768015330
11101536030690
12113072061410
131261440122850
1413122880245730

For example,

If the attempt fails, AfterShip will retry the 2nd attempt 30 seconds later.
If the 7th attempt fails, AfterShip will retry the 8th attempt 960 seconds later.
If the 14th attempt fails, AfterShip will no longer send out that webhook.