Setting up and getting started with the Rich Returns webhook is very simple: just go to the Account > Developers menu and then click the Webhooks tab.
This tab lists all the webhooks you’ve created.
Click the “Create Webhook” button to create a new one by filling in the required information as shown below:
In Rich Returns, the webhook runs whenever there is an update to an RMA.
Therefore, the “Webhook Name” and “Event” fields are intended solely for your own organization and do not affect the webhook’s functionality.
In the “URL” field, you must enter the URL that will receive the data sent by our webhook.
Don’t forget to make the webhook active and save!
When you save, the Secret Key token will be displayed. Copy it and store it in a safe place so that you’ll have it on hand when implementing it in your solution.
The data sent by the webhook follows the JSON structure below:
{
"data": {
"type": "event",
"attributes": {
"properties": {
"rma": "RMA-680648308273",
"status": "Approved",
"method": "methodLabelManual",
"staffNotes": null,
"createdAt": "2026-06-24T19:35:27+00:00",
"caseIssue": null,
"labelFeeAmount": "5.5",
"restockingFeeAmount": "2",
"restockingFeeType": "fixed",
"restockingFeeIncludeTax": false,
"shippingCosts": "0.00",
"photoUploadUrl1": null,
"photoUploadUrl2": null,
"photoUploadUrl3": null,
"labelObjectId": null,
"labelStatus": null,
"labelTrackingNumber": null,
"labelTrackingUrl": null,
"labelUrl": null,
"labelAmount": null,
"labelCurrency": null,
"customShippingLabelUrl": null,
"customShippingLabelSecondUrl": null,
"orderId": "18653680075056",
"orderNumber": "1031",
"orderDate": "2026-05-20T11:02:48-04:00",
"orderCurrency": "USD",
"orderTotal": "3001.93",
"orderLineItemTotal": "3001.93",
"orderDiscount": "0.00",
"orderTax": "0.00",
"orderTags": "",
"orderDiscountCodes": null,
"orderPaymentGateway": "manual",
"orderFulfillmentLocationId": "96719372592",
"refundAmountTotal": null,
"customerEmail": "[email protected]",
"customerFirstName": "Ayumu",
"customerLastName": "Hirano",
"customerMobile": null,
"customerLocale": "en",
"shippingAddressFirstName": "Ayumi",
"shippingAddressLastName": "Ayumi",
"shippingAddressAddress1": "10 Canlish Road",
"shippingAddressAddress2": "12",
"shippingAddressCity": "Toronto",
"shippingAddressZip": "M1P 1S4",
"shippingAddressProvince": "Ontario",
"shippingAddressProvinceCode": "ON",
"shippingAddressCountry": "Canada",
"shippingAddressCountryCode": "CA",
"shippingAddressPhone": null,
"Products": [
{
"lineItemId": "50194943607088",
"lineItemPrice": 25,
"lineItemDiscount": null,
"returnItemReason": "Didn't fit - Too large",
"returnItemResolution": "refundToExchange",
"returnItemResolutionLabel": "Exchange",
"returnItemQuantity": 1,
"returnItemNote": "-",
"productId": "9559630250288",
"productName": "Example T-Shirt",
"productVendor": "Acme",
"productImageUrl": "https://cdn.shopify.com/s/files/1/0865/9376/5680/files/T-Shirt-5e0117e02.webp?v=1723471643",
"productTags": "mens t-shirt example",
"productWeightInGrams": 3629,
"variantId": "48947089572144",
"variantSku": "",
"variantName": "Lithograph - Height: 9\" x Width: 12\" / Blue",
"inventoryItemId": null,
"stockLocationId": "96719372592",
"exchangeItemVariantId": "48947089768752",
"exchangeItemVariantName": "Medium / Blue",
"exchangeItemPrice": 27,
"exchangeItemWeightInGrams": 3629,
"lineItemRefund": null
}
]
},
"metric": {
"data": {
"type": "metric",
"attributes": {}
}
},
"profile": {
"data": {
"type": "profile",
"attributes": {}
}
}
}
}
}