Webhook Overview

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

When a "return" is created or updated in the AfterShip Returns (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). You can receive any field update by simply listening the the following events:

• return.created: Occurs when a return request is successfully submitted
• return.updated: Occurs whenever any field of a return request is updated.

There are also a few other events in smaller granularity that you can subscribed to, in case you want less amount of event updates:

Tracking status updates:

• return.shipment.updated: Occurs when a return shipment status is updated, e.g. moved to inTransit or Delivered state.

Parcel Collection Network Status Updates: If you use a parcel collection network provider such as Happy Returns/Hubbed to receive return items. Events below apply.

• return.dropoff.created: Occurs when a drop-off parcel QR code is generated for shoppers to take the items and drop them off at the parcel collection location.
• return.dropoff.updated: Occurs when a drop-off parcel is updated, e.g. when it is handed over to parcel collection location.
• return.dropoff.shipment.updated: Occurs when shipment statuses of drop-off items update, usually happens when the items are packed by the parcel collection provider and shipped to the warehouse of merchants. This shipment is outside the tracking scope of AfterShip but purely managed by the parcel network provider.

Please check out the detailed payload on this page.

---

How to setup the Webhooks

1. Ennable the webhook by visiting webhook configuration page. At the top right corner, switch to the organization you want to configure.

2. Fill in the form and save your webhook configuration. You will then see a secret at the configuration page. The secret is for you to verify that the sender is from AfterShip following this implementation later on. Now to test out the webhooks, either submit a new return request or edit the notes on existing RMAs, webhooks then fires immediately.

Securing Webhooks

We provide a few options for you to securely verify that the sender is from AfterShip.

• IP allowlist
• Signature Verification

We currently support only 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 retry	Delay (sec) before send out	Acc. Delay (sec)
1	0	0	0
2	1	30	30
3	2	60	90
4	3	120	210
5	4	240	450
6	5	480	930
7	6	960	1890
8	7	1920	3810
9	8	3840	7650
10	9	7680	15330
11	10	15360	30690
12	11	30720	61410
13	12	61440	122850
14	13	122880	245730

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.