Webhook Overview

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

Webhook Events

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

Claim status updates

You can receive Claim status update by simply listening the the following events:

• warranty.created: Occurs when a warranty request is successfully submitted.
• warranty.approved: Occurs when a warranty request is approved, indicating that the warranty claim has been accepted.
• warranty.processing: Occurs when a warranty request is being processed, typically involving inspection or evaluation of the claimed item.
• warranty.completed: Occurs when a warranty request has been successfully processed and the necessary actions, such as repair or replacement, have been completed
• warranty.canceled: Occurs when a warranty request is canceled, indicating that the warranty claim will not be processed further.
• warranty.rejected: Occurs when a warranty request is rejected, indicating that the warranty claim has been denied or deemed ineligible.
• warranty.inbound_shipment.provided: Occurs when the inbound shipment details for returning the item covered under warranty are provided.
• warranty.inbound_shipment.updated: Occurs when there is an tracking update in the inbound shipment details provided for returning the item covered under warranty.
• warranty.outbound_shipment.provided: Occurs when the outbound shipment details for sending the repaired or replaced item back to the customer are provided.
• warranty.outbound_shipment.updated: Occurs when there is an tracking update in the outbound shipment details provided for sending the repaired or replaced item back to the customer.

Claim Life Cycle

This table list out the most common usages of the webhooks.

Claim Life Cycle	Webhook Event	Critical Payload Fields
Warranty request submitted and under review.	warranty.created	status=under_review
Warranty request approved.	warranty.approved	status=approved
Warranty request is being processed.	warranty.processing	status=in_process
Warranty request has been successfully resolved.	warranty.completed	status=completed
Warranty request is canceled.	warranty.canceled	status=canceled
Warranty request is rejected.	warranty.rejected	status=rejected
Warranty request labels in the inbound shipment were fully generated/uploaded.	warranty.inbound_shipment.provided	status=approved
Tracking status in the inbound shipment is updated.	warranty.inbound_shipment.updated	status=approved or status=in_process
Warranty request labels in the outbound shipment were fully generated/uploaded.	warranty.outbound_shipment.provided	status=completed
Tracking status in the outbound shipment is updated.	warranty.outbound_shipment.updated	status=completed

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 warranty request or edit the notes on existing RMAs, webhooks then fires immediately.

Make Your Integration Backward-Compatible

The webhook enum values are not restrictive and may be extended with more options as the product evolves. To avoid accidental crashes in your webhook integration, please do not define restrictive, fixed enum options in your code. Instead, treat the enum as just a string in your program and be prepared for the possibility of new kinds of values appearing in the future.

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.