Webhooks & Notifications - Return Helper API

Overview

Webhooks deliver asynchronous notifications when events occur in the Return Helper system — for example, when a label is generated or a shipment arrives at the warehouse. Your server must expose an HTTPS endpoint to receive these POST requests.

Setting Up Your Webhook Endpoint

Endpoint Requirements

Before submitting a setup request, make sure your endpoint meets the following requirements:

Publicly accessible — the URL must be reachable from the internet (no VPN, localhost, or internal-only addresses)
HTTPS — the endpoint must be served over HTTPS with a valid TLS certificate
HTTP POST — the endpoint must accept POST requests with a application/json body
Respond HTTP 200 — your server must return a 200 OK status promptly after receiving the request; any other status code or a timeout is treated as a failed delivery
Fast response — process the event asynchronously if needed; do not perform heavy work before responding, to avoid delivery timeouts

Registering Your Endpoint

To register your webhook endpoint, please fill in the Webhook Setup Request Form. The form contains all the information we need to complete the setup quickly, and is the fastest way to get your endpoint activated.

We recommend using the form above, as it ensures all required details are captured in one step. If you are unable to use the form, you may also send the request by email — see the template below.

Email template (if you cannot use the form)

If you prefer to contact us by email, send the following to support@returnhelper.com:

Subject: Request webhook setup in Return Helper - <YOUR CLIENT CODE>

To: support@returnhelper.com

Dear Support Team,

We would like to request webhook setup in Return Helper. Please find the details below:

Email address: <YOUR EMAIL ADDRESS>
Client code:   <YOUR CLIENT CODE>
Endpoint:      https://your-server.example.com/webhook
Environment:   <Sandbox / Production / Both>
Comments:      <Any additional information, or leave blank>

Event Delivery

Timing — Events may arrive a few seconds after the triggering action, and in rare cases up to a few minutes later. Duplicate events — Your endpoint may receive the same event more than once. Track processed notificationId values to deduplicate; notificationId is unique per event and present on every webhook notification, so it is a stable idempotency key on its own. Event ordering — Delivery order is not guaranteed. Design your handler to process events in any order. For example, inventoryCreated may arrive before warehouseMarkShipmentArrivedV2. Use the API to fetch any objects referenced in events you receive out of sequence. Each event includes an eventTime field in ISO 8601 format.

Notification Headers

Every webhook request includes these headers:

Header	Type	Description
`RETURNHELPER-TRIGGERED-AT`	string	ISO 8601 timestamp in UTC, for example `2026-08-14T09:31:02.1234567Z`. This is the value used in signature verification.
`RETURNHELPER-API-ID`	string	The `apiId` of the account the notification belongs to. Retrieve yours with Get API account information.
`RETURNHELPER-API-NAME`	string	The `apiName` of that account.
`ReturnHelper-Signature`	string	HMAC-SHA256 signature for verification — see Signature Verification.

Legacy headers

These headers are still sent on every notification and are not being removed. New integrations should read the headers above instead.

Legacy header	Replaced by
`Timestamp`	`RETURNHELPER-TRIGGERED-AT` — same value, character for character.
`x-returnhelper-apiname`	`RETURNHELPER-API-NAME` — same value.

HTTP header names are case-insensitive, and some frameworks normalise them. The casing above is what Return Helper sends on the wire; if your framework lowercases incoming header names, match them case-insensitively.

Signature Verification

Always verify the signature before processing any payload. Use the raw request body — any transformation (e.g. by a framework that re-serialises JSON) will cause verification to fail.

Your signing key is provided by Return Helper (it is Base64-encoded). Store it securely and never expose it. You can find it in the User Portal on the same screen as your API key and token — see the screenshot under Authentication — or read it programmatically with Get signing key.

Worked Example

Given the following incoming request: Headers:

{
  "content-type": "application/json; charset=utf-8",
  "ReturnHelper-Signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "RETURNHELPER-TRIGGERED-AT": "2024-01-12T09:23:08.4863561Z",
  "RETURNHELPER-API-ID": "12345",
  "RETURNHELPER-API-NAME": "Acme Returns",
  "Timestamp": "2024-01-12T09:23:08.4863561Z"
}

Body (raw JSON, must not be re-serialised):

{"label":{"regions":{"RHCN":"https://label.returnhelperchina.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf"},"labelId":31033,"shipmentId":30385,"apiId":33,"refKey":"S240112-0000001","labelRequestStatusCode":"success","serviceType":"RETURN_ENDICIA_USPS_GROUND_ADVANTAGE_NJ","trackingNumber":"9434611899562082901137","labelUrl":"https://label-service-dev-files.returnshelper.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf","error":null,"qrcodeUrl":null,"qrcodeError":null,"correlationId":null,"cancelCutoffTime":"2024-02-11T09:21:24.0795","meta":null},"category":"labelGenerated","action":"labelGenerated","eventTime":"2024-01-12T09:23:08.4862743Z"}

Step-by-Step Verification

Step 1 — Extract the signature from the ReturnHelper-Signature header (for comparison at the end):

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

Step 2 — Extract the timestamp from the RETURNHELPER-TRIGGERED-AT header:

2024-01-12T09:23:08.4863561Z

Step 3 — Build the string_to_sign Concatenate these four values in order (no separator):

HTTP method: POST
Your notification endpoint URL: https://s2024-01-12.free.beeceptor.com
The RETURNHELPER-TRIGGERED-AT value from Step 2
The raw JSON body

The resulting concatenated string:

POSThttps://s2024-01-12.free.beeceptor.com2024-01-12T09:23:08.4863561Z{"label":{"regions":...},...}

Then Base64-encode the entire concatenated string. The result is the string_to_sign:

UE9TVGh0dHBzOi8vczIwMjQtMDEtMTIuZnJlZS5iZWVjZXB0b3IuY29tMjAyNC0wMS0xMlQwOToyMzowOC40ODYzNTYxWnvigJxsYWJlbOKAnTp74oCccmVnaW9uc+KAnTp74oCcUkhDTuKAnTrigJxodHRwczovL2xhYmVsLnJldHVybmhlbHBlcmNoaW5hLmNvbS9sYWJlbC8yMDI0MDEvMTA1OTUtUzI0MDExMi0wMDAwMDAxLXBxazJwdnlkZ3hwLnBkZuKAnX0s4oCcbGFiZWxJZOKAnTozMTAzMyzigJxzaGlwbWVudElk4oCdOjMwMzg1LOKAnGFwaUlk4oCdOjMzLOKAnHJlZktleeKAnTrigJxTMjQwMTEyLTAwMDAwMDHigJ0s4oCcbGFiZWxSZXF1ZXN0SWTigJ06MTA1OTUs4oCcbGFiZWxSZXF1ZXN0U3RhdHVzQ29kZeKAnTrigJxzdWNjZXNz4oCdLOKAnHNlcnZpY2VUeXBl4oCdOuKAnFJFVFVSTl9FTkRJQ0lBX1VTUFNfR1JPVU5EX0FEVkFOVEFHRV9OSuKAnSzigJx0cmFja2luZ051bWJlcuKAnTrigJw5NDM0NjExODk5NTYyMDgyOTAxMTM3IizigJxsYWJlbFVybOKAnTrigJxodHRwczovL2xhYmVsLXNlcnZpY2UtZGV2LWZpbGVzLnJldHVybnNoZWxwZXIuY29tL2xhYmVsLzIwMjQwMS8xMDU5NS1TMjQwMTEyLTAwMDAwMDEtcHFrMnB2eWRneHAucGRm4oCdLOKAnGVycm9y4oCdOm51bGws4oCccXJjb2RlVXJs4oCdOm51bGws4oCccXJjb2RlRXJyb3LigJ06bnVsbCzigJxjb3JyZWxhdGlvbklk4oCdOm51bGws4oCcY2FuY2VsQ3V0b2ZmVGltZeKAnTrigJwyMDI0LTAyLTExVDA5OjIxOjI0LjA3OTUiLOKAnG1ldGHigJ06bnVsbH0s4oCcY2F0ZWdvcnnigJ064oCcbGFiZWxHZW5lcmF0ZWTigJ0s4oCcYWN0aW9u4oCdOuKAnGxhYmVsR2VuZXJhdGVk4oCdLOKAnGV2ZW50VGltZeKAnTrigJwyMDI0LTAxLTEyVDA5OjIzOjA4LjQ4NjI3NDNa4oCdfQ==

Step 4 — Compute the HMAC-SHA256 signature Using the example signing key (your actual key will be different):

PEnA0mzKb7fUlGfMgCGhXPjPmPGvW70UU8bkNKdG78WDrQRwzFa572e2JsFIE1e4PLaP9h/ZEvERSR0FBDYNlQ==

Operations:

Decode the string_to_sign (from Step 3) from Base64 → byte array
Decode your signing key from Base64 → byte array
Compute HMAC-SHA256 using the signing key bytes over the string_to_sign bytes → signature byte array
Base64-encode the signature byte array

Expected result:

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

Step 5 — Compare signatures Compare the signature computed in Step 4 with the one extracted in Step 1. Use a constant-time string comparison to prevent timing attacks. Additional security: Reject events where eventTime differs from your system clock by more than 15 minutes (replay attack protection).

Sample Code

// Required imports (add at the top of your file):
//   import java.security.InvalidKeyException;
//   import java.security.NoSuchAlgorithmException;
//   import javax.crypto.Mac;
//   import javax.crypto.spec.SecretKeySpec;
//   import org.apache.commons.codec.binary.Base64;

class Main {
  private static final String CHARACTER_ENCODING = "UTF-8";
  final static String ALGORITHM = "HmacSHA256";

  public static void main(String[] args) throws Exception {
    String payload   = "<body JSON string>";
    String action    = "<action>";           // always "POST"
    String url       = "<url>";              // your notification endpoint
    String timestamp = "<timestamp>";        // from RETURNHELPER-TRIGGERED-AT header

    String data = new String(
      Base64.encodeBase64((action + url + timestamp + payload).getBytes(CHARACTER_ENCODING))
    );

    String base64Key  = "<signing key>";
    String signature  = sign(data, base64Key);
    System.out.println(signature);
  }

  private static String sign(String data, String secretKey)
      throws NoSuchAlgorithmException, InvalidKeyException {
    Mac mac = Mac.getInstance(ALGORITHM);
    mac.init(new SecretKeySpec(Base64.decodeBase64(secretKey), ALGORITHM));
    byte[] signature = mac.doFinal(Base64.decodeBase64(data));
    return new String(Base64.encodeBase64(signature), CHARACTER_ENCODING);
  }
}

// Node.js built-in module. Import at the top of your file:
//   import * as crypto from 'node:crypto';   // ESM
//   const crypto = require('node:crypto');   // CommonJS

function sign(data, secretKey) {
  const key        = Buffer.from(secretKey, 'base64');
  const hmac       = crypto.createHmac('sha256', key);
  const dataBuffer = Buffer.from(data, 'base64');
  hmac.update(dataBuffer);
  return hmac.digest('base64');
}

async function main() {
  const payload   = '<body JSON string>'; // raw request body
  const action    = '<action>';           // always "POST"
  const url       = '<url>';              // your notification endpoint
  const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

  const encodedData = Buffer.from(action + url + timestamp + payload).toString('base64');
  const base64Key   = '<signing key>';
  const signature   = sign(encodedData, base64Key);

  console.log('Signature:', signature);
}

main().catch(console.error);

// Node.js built-in module. Import at the top of your file:
//   import * as crypto from 'node:crypto';

function sign(data: string, secretKey: string): string {
  const key         = Buffer.from(secretKey, 'base64');
  const hmac        = crypto.createHmac('sha256', key);
  const decodedData = Buffer.from(data, 'base64');
  hmac.update(decodedData);
  return hmac.digest('base64');
}

function main() {
  const payload   = '<body JSON string>'; // raw request body
  const action    = '<action>';           // always "POST"
  const url       = '<url>';              // your notification endpoint
  const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

  const encodedData = Buffer.from(action + url + timestamp + payload, 'utf-8').toString('base64');
  const base64Key   = '<signing key>';
  const signature   = sign(encodedData, base64Key);

  console.log(signature);
}

main();

public class Main {
    private static final String ALGORITHM = 'HmacSHA256';

    public static void main() {
        String payload   = '<body JSON string>'; // raw request body
        String action    = '<action>';            // always 'POST'
        String url       = '<url>';               // your notification endpoint
        String timestamp = '<timestamp>';         // from RETURNHELPER-TRIGGERED-AT header

        Blob data        = EncodingUtil.base64Encode(
                               Blob.valueOf(action + url + timestamp + payload));
        String base64Key = '<signing key>';
        String signature = sign(data, base64Key);
        System.debug(signature);
    }

    private static String sign(Blob data, String secretKey) {
        Blob macKey   = EncodingUtil.base64Decode(secretKey);
        Blob sigBytes = Crypto.generateMac(ALGORITHM, data, macKey);
        return EncodingUtil.base64Encode(sigBytes);
    }
}

Retry Mechanism

Respond with a 2xx HTTP status code to acknowledge receipt. Non-2xx responses trigger retries. After 10 consecutive failures, notification delivery to your endpoint is suspended for 24 hours.

Common Body Fields

All notification bodies share these top-level fields:

Field	Type	Description
`category`	string	Notification category (see table below)
`action`	string	Specific event action
`eventTime`	string	ISO 8601 timestamp of the event
`version`	string	Notification schema version
`notificationId`	string	Unique per event. Present on every webhook notification — use this as your idempotency key.

Notification Event Reference

Notification	`category`	`action`	Description
Label result	`labelGenerated`	`labelGenerated`	Label generation result (success or failure)
Warehouse shipment arrived (v2)	`rsl`	`markShipmentArrive`	Shipment received at warehouse (current version)
Inventory created	`newInventoryCreated`	`newInventoryCreated`	New return inventory created
Image updated	`rrli`	`changeLineItemImage`	Line item image added, changed, or removed
Unknown shipment assigned	`rsl`	`assignUnknown`	Unknown shipment assigned to seller
Recall status update	`recall`	`recallUpdateStatus`	Recall tracking or pick-up status changed
Resend status update	`resend`	`updateResendStatus`	Resend tracking or status changed
VAS update	`rrliv`	`vasUpdated`	Value-added service completed or updated
Inventory handling complete	`rinv`	`completeInventoryHandling`	Handling instruction completed
Inventory recalibrated	`completeRecalibrate`	`completeRecalibrate`	Warehouse updated inventory dimensions/weight
Inventory meta updated	`updateReturnInventoryMeta`	`updateReturnInventoryMeta`	Warehouse or user added/updated meta data
RMA updated	`notifyUserRmaSwapped`	`notifyUserRmaSwapped`	Warehouse corrected an RMA assignment
SKU updated	`userUpdateReturnInventorySku`	`userUpdateReturnInventorySku`	Seller updated inventory SKU
Split line item	`lineItemVasReturnInventoryLineItem`	`splitLineItem`	VAS split a parcel into multiple inventories
Warehouse remarks updated	`warehouseUpdateWarehouseRemarks`	`warehouseUpdateWarehouseRemarks`	Warehouse updated remarks on a return request
Buyer return label generated	`buyerReturnRrLabel`	`buyerReturnLabelGenerated`	Branded return portal label generated for buyer
Shopify buyer return created	`shopifyBuyerCreateReturn`	`shopifyBuyerCreateReturn`	Buyer created a return via Shopify integration
Consolidate shipping cost updated	`consolidateShippingOrderShippingFeeUpdated`	`consolidateShippingOrderShippingFeeUpdated`	Consolidated shipping order cost updated
Consolidate shipping all packed	`consolidateShippingOrderInventoryAllPacked`	`consolidateShippingOrderInventoryAllPacked`	All inventories packed for a consolidated order
Consolidate shipment sent	`consolidateShippingShipmentSent`	`consolidateShippingShipmentSent`	Consolidated shipment dispatched to carrier
Consolidate shipping AWB updated	`consolidateShippingShipmentShipped`	`consolidateShippingShipmentShipped`	Consolidated shipment AWB updated
Consolidate order completed	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	All shipments in a consolidated order shipped
Consolidate order cancelled	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	Consolidated order force-cancelled by warehouse

Notification Payloads

Label Result

Sent when a return label request completes (success or failure).

Always use shipmentId to match labels to shipments in your system — do not use labelId. In rare cases a carrier failure causes a new label (with a new labelId) to be issued for the same shipmentId.

category: labelGenerated / action: labelGenerated Key fields in label:

Field	Description
`labelId`	Label identifier (do not use for matching — see warning above)
`shipmentId`	Shipment identifier (use this for matching)
`apiId`	Seller API ID
`refKey`	Shipment reference key
`labelRequestStatusCode`	`"success"` or `"fail"`
`serviceType`	Carrier service type used
`trackingNumber`	Carrier tracking number (on success)
`labelUrl`	URL to download label PDF (on success)
`error`	Error message (on failure)
`qrcodeUrl`	QR code URL (if applicable)
`qrcodeError`	QR code error (if applicable)
`shipmentInstruction`	Shipment instructions
`correlationId`	Correlation ID for request tracing
`cancelCutoffTime`	Deadline to cancel this label
`meta`	Additional metadata
`regions`	Map of region codes to regional label URLs

Success example:

{
  "label": {
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://example.com/label.pdf",
    "qrcodeUrl": "https://example.com/qrcode.png",
    "qrcodeError": null,
    "error": null,
    "correlationId": null,
    "meta": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-04T17:03:15.8888073Z"
}

Failure example:

{
  "label": {
    "labelId": 11352,
    "shipmentId": 10833,
    "apiId": 21,
    "refKey": "S210906-0000085",
    "labelRequestStatusCode": "fail",
    "serviceType": "ap",
    "trackingNumber": null,
    "labelUrl": null,
    "error": "Your combination of suburb, state & postcode doesn't match.",
    "qrcodeUrl": null,
    "qrcodeError": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-06T08:16:33.4674332Z"
}

Warehouse Shipment Arrived (v2)

Sent when a warehouse marks a shipment received. Always followed by one or more Inventory Created events.

This event echoes your sellerReferenceNumber and is the primary reconciliation point between your order records and Return Helper’s identifiers. The V202207 default carries SRN at all three layers in one bundled payload; V202407 carries only the Shipment-layer SRN. See Seller Reference Number for the full reconciliation workflow and version differences.

category: rsl / action: markShipmentArrive / version: 202407 Key fields in shipment:

Field	Description
`shipmentId`	Unique shipment identifier
`returnRequestId`	Linked return request
`trackingNumber`	Carrier tracking number
`sellerReferenceNumber`	Your reference number
`serviceType`	Shipping service used
`customFieldMap`	Custom fields from the original shipment
`shipToWarehouseId`	Receiving warehouse
`receiveDate`	ISO 8601 receive timestamp

{
  "shipment": {
    "shipmentId": "35732",
    "sellerReferenceNumber": "R240725-0000003",
    "returnRequestId": "66848",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "R240725-0000003",
    "serviceType": "fedex",
    "customFieldMap": {
      "customerId": "buyer123"
    },
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-25T08:53:05.7827073Z"
  },
  "category": "rsl",
  "action": "markShipmentArrive",
  "eventTime": "2024-07-29T05:48:21.381658Z",
  "version": "202407"
}

Inventory Created

Sent after a shipment is received (or a VAS split occurs) to notify that a new return inventory record has been created. One event is sent per inventory item — a single shipment may produce multiple events if multiple packages were received under the same label.

No sellerReferenceNumber in this payload. Neither returnInventory nor shipment carries sellerReferenceNumber; only shipment.referenceNumber is present, and that field echoes the orderNumber you supplied — not the seller reference. If you rely on sellerReferenceNumber to reconcile inventory back to your own records, do not subscribe to newInventoryCreated alone. Pair it with Warehouse Shipment Arrived (carries SRN at all three layers in V202207) or Inventory Handling Complete (carries the Line-Item SRN on returnInventory.sellerReferenceNumber). See Seller Reference Number for the full reconciliation strategy.

category: newInventoryCreated / action: newInventoryCreated Key fields in returnInventory:

Field	Description
`returnInventoryId`	Unique inventory identifier — use this to assign handling
`warehouseId`	Warehouse where inventory is held
`rma`	Warehouse-assigned RMA value
`handlingCode`	Current handling instruction
`handlingStatusCode`	Current handling status
`imageList`	Images captured at receipt
`returnInventoryMetaList`	Additional metadata (e.g. custom fields from shipment)

{
  "returnInventory": {
    "returnInventoryId": "19973",
    "warehouseId": 2,
    "apiId": 21,
    "description": "Item description",
    "quantity": 1,
    "dimension1": 20,
    "dimension2": 20,
    "dimension3": 22,
    "dimensionUom": "cm",
    "weight": 300,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 10,
    "handlingCode": "tbc",
    "handlingStatusCode": "pending",
    "completeOn": null,
    "warehouseRemarks": null,
    "handlingUpdatedOn": "2024-07-15T03:29:53.889398",
    "sku": null,
    "rma": "USE-2-240715-D00003-30",
    "modifyOn": "2024-07-15T03:29:53.903982",
    "createOn": "2024-07-15T03:29:53.88968",
    "imageList": [
      {
        "imageUrl": "https://example.com/image1.jpg",
        "imageKey": "images/returns/202407/image1.jpg"
      }
    ],
    "returnInventoryMetaList": [
      {
        "metaType": "shipmentCustomField",
        "metaMap": {
          "customerId": "buyer123"
        }
      }
    ]
  },
  "shipment": {
    "shipmentId": "9999",
    "returnRequestId": "1234",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "",
    "serviceType": "fedex",
    "customFieldMap": {},
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-15T03:29:00.000000"
  },
  "category": "newInventoryCreated",
  "action": "newInventoryCreated",
  "eventTime": "2024-07-15T03:30:05.1984163Z",
  "version": "202207"
}

Image Updated

Sent when images are added, changed, or removed for a return inventory line item. category: rrli / action: changeLineItemImage Top-level payload fields:

Field	Type	Description
`imageUrlList`	array of strings	Current image URLs for this line item
`returnRequestLineItem`	object	The affected line item (see below)

Key fields in returnRequestLineItem:

Field	Description
`returnRequestLineItemId`	Line item identifier
`apiId`	Seller API ID
`returnRequestId`	Linked return request ID
`sellerReferenceNumber`	Seller’s reference number
`description`	Item description
`quantity`	Item quantity
`weight` / `weightUom`	Weight and unit
`valueCurrencyCode` / `value`	Value and currency
`handlingCode`	Handling instruction
`isDeleted`	Whether line item is deleted
`rma`	RMA value
`isFraudulent`	Fraud flag
`fraudReasonCode`	Fraud reason code (if flagged)
`customFieldMap`	Custom fields

{
  "imageUrlList": [
    "https://file.returnhelpercentre.com/img/returns/202606/27_1000040536_lmpiohbx.5n3.jpg",
    "https://file.returnhelpercentre.com/images/returns/202603/16209788537041243876_USE-21-260303-P00156-19_..._4290.jpg"
  ],
  "returnRequestLineItem": {
    "returnRequestLineItemId": 10759,
    "apiId": 21,
    "returnRequestId": 9237,
    "returnRequestLineItemNumber": "RL210706-0000020",
    "sellerReferenceNumber": "RL210706-0000020",
    "description": "Item description",
    "quantity": 1,
    "weight": 100.0,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 463.0,
    "handlingCode": 0,
    "isDeleted": false
  },
  "category": "rrli",
  "action": "changeLineItemImage",
  "eventTime": "2021-07-06T13:02:24.5575164Z"
}

URLs in imageUrlList are publicly fetchable, do not expire, and are safe to cache client-side. Persist them as-is. Empty state: imageUrlList: [].

Unknown Shipment Assigned

Sent when a shipment with no prior return request is identified and assigned to a seller. category: rsl / action: assignUnknown / version: 202407 Key fields in returnInventory:

Field	Description
`returnInventoryId`	Unique inventory identifier
`warehouseId`	Warehouse where inventory is held
`apiId`	Seller API ID
`description`	Item description
`quantity`	Item quantity
`dimension1` / `dimension2` / `dimension3`	Measured dimensions
`dimensionUom`	Dimension unit of measurement
`weight`	Measured weight
`weightUom`	Weight unit of measurement
`valueCurrencyCode`	Value currency code
`value`	Declared value
`handlingCode`	Current handling instruction
`handlingStatusCode`	Current handling status
`completeOn`	Handling completion timestamp
`warehouseRemarks`	Warehouse remarks
`handlingUpdatedOn`	Last handling update timestamp
`sku`	SKU assigned by seller
`rma`	Warehouse-assigned RMA
`modifyOn` / `createOn`	Audit timestamps
`imageList`	Images captured at receipt

Key fields in unknownShipment:

Field	Description
`unknownShipmentId`	Unique unknown shipment identifier
`unknownShipmentNumber`	Unknown shipment reference number
`description`	Description
`unknownShipmentStatusCode`	Current status
`unknownShipmentCountryCode`	Country code
`warehouseId`	Receiving warehouse
`unknownShipmentServiceType`	Shipping service type
`trackingNumber`	Carrier tracking number
`totalWeight` / `totalWeightUom`	Total weight and unit
`dimension1` / `dimension2` / `dimension3`	Measured dimensions
`dimensionUom`	Dimension unit of measurement
`totalValue` / `totalValueCurrency`	Declared value and currency
`modifyOn`	Last modified timestamp

Recall Status Update

Sent when a recall tracking number is updated or pick-up status changes. category: recall / action: recallUpdateStatus recallUpdateTypeStatus values:

Value	Recall Inventory Status	Description
`updateTrackingNumber`	`in-transit`	Tracking number assigned
`readyToPickUp`	`ready-to-pick-up`	Item ready for pick-up
`pickupBySelf`	`picked-up`	Picked up by customer
`pickupByCourier`	`picked-up`	Picked up by local courier
`pickupByOthers`	`picked-up`	Picked up by another party

{
  "recall": {
    "apiId": 103,
    "recallId": 938,
    "recallNumber": "RCL240423-0000001",
    "recallStatusCode": "in-progress",
    "warehouseRemarks": null,
    "recallInventoryList": [
      {
        "recallInventoryId": 1145,
        "returnInventoryId": 18600,
        "recallInventoryStatusCode": "in-transit",
        "pickUpCode": "pending",
        "trackingNumber": "AWB-TRACKING-NUMBER",
        "listName": null,
        "weight": null,
        "amount": null,
        "pickUpOn": null,
        "courierTrackingNumber": null,
        "remarks": null,
        "recallServiceType": "dhl",
        "rma": "USE-1005-240523-D00001-25"
      }
    ]
  },
  "recallUpdateTypeStatus": "updateTrackingNumber",
  "category": "recall",
  "action": "recallUpdateStatus",
  "eventTime": "2024-04-23T07:50:49.2479819Z"
}

Resend Status Update

Sent when a resend tracking number is updated or the resend completes or fails. category: resend / action: updateResendStatus Top-level payload fields:

Field	Type	Description
`resend`	object	Resend order details (see below)
`returnInventoryList`	array	Inventory items being resent
`resendShipmentList`	array	The resend shipment for this resend (see below)

Key fields in resend:

Field	Description
`resendId`	Unique resend order identifier
`apiId`	Seller API ID
`resendNumber`	Resend order number
`resendStatusCode`	Current status: `0` — pending, `1` — canceled, `2` — in progress, `3` — completed, `4` — failed, `5` — queued, `6` — label success
`description`	Order description
`remarks`	Seller remarks
`warehouseRemarks`	Warehouse remarks

Key fields in each resendShipmentList entry:

Field	Description
`resendShipmentId`	Resend shipment identifier
`resendId`	Resend order this shipment belongs to
`resendShipmentNumber`	Resend shipment number
`trackingNumber`	Carrier tracking number (when available)
`sellerReferenceNumber`	Your own reference for this resend
`error`	Error message (when the shipment failed)

resendShipmentList always contains exactly one entry — a resend has one and only one resend shipment. Read it as resendShipmentList[0].

trackingNumber is not a top-level field. It lives on the resend shipment: resendShipmentList[0].trackingNumber.

Check resend.resendStatusCode:

3 — completed (read resendShipmentList[0].trackingNumber)
4 — failed (read resendShipmentList[0].error)

{
  "resend": {
    "resendId": 2902,
    "apiId": 21,
    "resendNumber": "RSD221003-0000001",
    "resendStatusCode": 3
  },
  "returnInventoryList": [
    {
      "returnInventoryId": 14129,
      "rma": "SGP240101-0000001"
    }
  ],
  "resendShipmentList": [
    {
      "resendShipmentId": 2897,
      "resendId": 2902,
      "resendShipmentNumber": "RSDS221003-0000001",
      "trackingNumber": "9201994884299101443342",
      "sellerReferenceNumber": "ORDER-0001",
      "error": null
    }
  ],
  "category": "resend",
  "action": "updateResendStatus"
}

Use resendShipmentList[0].sellerReferenceNumber to match the event to your own order record without storing Return Helper’s resendId.

sellerReferenceNumber only carries a value when the resend was created by an Enterprise account through Create resend by SKU with a reference supplied. It is null for every other resend. To look a resend up on demand by this value, use Search resend by seller reference number.

VAS Update

Sent when a value-added service completes. category: rrliv / action: vasUpdated Each item in updateVasList:

Field	Description
`returnRequestLineItemVasId`	VAS record identifier
`vasResult`	VAS result description
`weight` / `weightUom`	Weight and unit after VAS
`dimension1` / `dimension2` / `dimension3`	Dimensions after VAS
`dimensionUom`	Dimension unit of measurement
`vasStatusCode`	VAS status code
`imageUrlList`	VAS result images

{
  "updateVasList": [
    {
      "returnRequestLineItemVasId": 65205,
      "vasResult": "VAS result details",
      "weight": 1000.0,
      "weightUom": "g",
      "dimension1": 25.0,
      "dimension2": 20.0,
      "dimension3": 10.0,
      "dimensionUom": "cm",
      "vasStatusCode": "SUCCESSFUL",
      "imageUrlList": [
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011051_eu4jjyfj.wth.jpg",
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011050_0nfetxuv.5hb.jpg"
      ]
    }
  ],
  "category": "rrliv",
  "action": "vasUpdated",
  "eventTime": "2021-07-06T12:15:55.9038524Z"
}

URLs in imageUrlList are publicly fetchable, do not expire, and are safe to cache client-side. Persist them as-is. Empty state: imageUrlList: [] (some VAS types do not produce photos; the entry remains in updateVasList[] with an empty array).

Inventory Handling Complete

Sent when a handling instruction (dispose, resend, recall, etc.) is completed by the warehouse. category: rinv / action: completeInventoryHandling Key fields in returnInventory:

Field	Description
`returnInventoryId`	Unique inventory identifier
`warehouseId`	Warehouse where inventory is held
`returnRequestLineItemId`	Linked line item ID
`apiId`	Seller API ID
`returnRequestId`	Linked return request ID
`sellerReferenceNumber`	Seller’s reference number
`description`	Item description
`quantity`	Item quantity
`dimension1` / `dimension2` / `dimension3`	Measured dimensions
`dimensionUom`	Dimension unit of measurement
`weight`	Measured weight
`weightUom`	Weight unit of measurement
`valueCurrencyCode`	Value currency code
`value`	Declared value
`handlingCode`	Handling instruction (see table below)
`handlingStatusCode`	Handling status (see table below)
`completeBy`	User who completed handling
`completeOn`	Completion timestamp
`warehouseRemarks`	Warehouse remarks
`handlingUpdatedOn`	Last handling update timestamp
`stopAgingOn`	Aging stop timestamp
`sku`	SKU assigned by seller
`rma`	Warehouse-assigned RMA
`returnInventoryMetaList`	Additional metadata list

handlingCode values:

ID	Code	Description
0	`tbc`	To Be Confirmed
1	`rtn`	Recall
2	`dis`	Disposal
3	`rsd`	Resend
4	`ohd`	On Hold
5	`oth`	Others

handlingStatusCode values:

ID	Code	Description
0	`pending`	Pending
1	`inProgress`	In Progress
2	`completed`	Completed

Inventory Recalibrated

Sent when a warehouse updates the measured dimensions or weight of a return inventory. category: completeRecalibrate / action: completeRecalibrate Key fields in recalibrateSupplement:

Field	Description
`warehouseId`	Warehouse that performed recalibration
`returnInventoryId`	Affected inventory ID
`returnRequestLineItemId`	Linked line item ID
`rma`	RMA value
`dimension1` / `dimension2` / `dimension3`	Updated dimensions
`weight`	Updated weight
`recalibratedOn`	Recalibration timestamp
`returnInventoryMetaList`	Updated metadata list (each entry has `metaType` and `metaMap`)

{
  "recalibrateSupplement": {
    "warehouseId": 8,
    "returnInventoryId": 18191,
    "returnRequestLineItemId": 38320,
    "rma": "USE-1005-240523-D00001-25",
    "dimension1": 20.0,
    "dimension2": 20.0,
    "dimension3": 20.0,
    "weight": 310.0,
    "recalibratedOn": "2024-04-04T00:42:11.1325135Z"
  },
  "category": "completeRecalibrate",
  "action": "completeRecalibrate",
  "eventTime": "2024-04-04T00:54:29.4337417Z"
}

Inventory Meta Updated

Sent when a warehouse or user adds or updates metadata on a return inventory. category: updateReturnInventoryMeta / action: updateReturnInventoryMeta The payload contains returnInventory with the same structure as Inventory Created, including the updated returnInventoryMetaList. metaType values:

usr — user-supplied meta
whs — warehouse-supplied meta

RMA Updated

Sent when a warehouse corrects an incorrect RMA assignment. category: notifyUserRmaSwapped / action: notifyUserRmaSwapped Key fields in payload:

Field	Description
`userApiId`	Seller API ID
`clientCode`	Client code
`returnInventoryId`	Affected inventory ID
`oldRma`	Previous RMA value
`newRma`	New corrected RMA value

{
  "payload": {
    "userApiId": 21,
    "clientCode": "RH21",
    "returnInventoryId": "19029",
    "oldRma": "USE-2-240517-D00026-56",
    "newRma": "USE-2-240520-D00001-35"
  },
  "category": "notifyUserRmaSwapped",
  "action": "notifyUserRmaSwapped",
  "eventTime": "2024-05-23T06:26:43.4416977Z"
}

SKU Updated

Sent when a seller updates the SKU of a return inventory. category: userUpdateReturnInventorySku / action: userUpdateReturnInventorySku The payload contains returnRequest and returnInventory. Key fields in returnRequest:

Field	Description
`returnRequestId`	Unique return request identifier
`apiId`	Seller API ID
`sellerReferenceNumber`	Seller’s reference number
`returnStatusCode`	Return request status
`returnTitle`	Return title
`totalValue` / `totalValueCurrency`	Total declared value and currency
`remarks`	Remarks
`rma`	RMA value
`isArchived`	Whether the request is archived
`returnRequestSourceType`	Source type of the return request

The returnInventory object follows the same structure as Inventory Handling Complete, with the updated sku field.

Split Line Item

Sent when a VAS operation splits a parcel into multiple inventories. Contains the new line item and inventory records for each resulting parcel. category: lineItemVasReturnInventoryLineItem / action: splitLineItem Top-level payload fields:

Field	Type	Description
`returnRequestId`	integer	Linked return request ID
`returnRequestLineItemId`	long	Original line item ID
`returnRequestLineItemVasId`	long	VAS record ID that triggered the split
`vasStatusCode`	string	VAS status code
`splitLineItemAndReturnInventoryList`	array	List of resulting split items (see below)

Each item in splitLineItemAndReturnInventoryList contains:

Field	Type	Description
`returnRequestLineItem`	object	New line item record (includes `returnRequestLineItemId`, `sellerReferenceNumber`, `description`, `quantity`, `weight`, `weightUom`, `valueCurrencyCode`, `value`, `handlingCode`, `rma`, `customFieldMap`)
`returnInventory`	object	New inventory record (same structure as Inventory Handling Complete)
`returnRequestLineItemSupplement`	object	Supplement with dimensions and weight for the new line item

Warehouse Remarks Updated

Sent when a warehouse updates remarks on a return request. category: warehouseUpdateWarehouseRemarks / action: warehouseUpdateWarehouseRemarks The payload contains three objects:

returnRequest — the return request (same structure as SKU Updated → returnRequest)
shipment — the shipment record with full address details, dimensions, weight, cost, and customFieldMap
returnInventory — the affected inventory (same structure as Inventory Handling Complete), with the updated warehouseRemarks field

Buyer Return Label Generated

Sent when a buyer creates a return in the Branded Return portal and a label is generated.

Only applicable to customers integrated with the Return Helper Branded Return service.

category: buyerReturnRrLabel / action: buyerReturnLabelGenerated Check buyerReturn.labelRequestStatusCode for "success" or "fail". Key fields in buyerReturn:

Field	Description
`buyerReturnId`	Unique buyer return identifier
`apiId`	Seller API ID
`sellerReferenceNumber`	Seller’s reference number
`returnRequestId`	Linked return request ID (if created)
`shipmentId`	Linked shipment ID (if created)
`returnRequestNumber`	Return request number
`shipmentNumber`	Shipment number
`totalValue` / `totalValueCurrency`	Declared value and currency
`remarks`	Remarks
`labelId`	Label ID
`labelRequestStatusCode`	`"success"` or `"fail"`
`trackingNumber`	Tracking number (on success)
`labelFile`	Object with `labelUrl` and `labelKey`
`shipmentInstruction`	Shipment instructions
`error`	Error message (on failure)
`warehouseId`	Destination warehouse
`shipmentServiceType`	Shipping service type
`shipmentCountryCode`	Shipment country
`shipmentName` / `shipmentPhone` / `shipmentEmail`	Contact details
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	Address lines
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	Address details
`costCurrencyCode` / `cost`	Shipping cost
`sellerCostCurrencyCode` / `sellerCost`	Seller cost
`buyerCostCurrencyCode` / `buyerCost`	Buyer cost
`boxType`	Box type
`weight` / `weightUom`	Weight and unit
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	Parcel dimensions
`customFieldMap`	Custom fields
`buyerReturnLineItemList`	List of line items (see below)

Each item in buyerReturnLineItemList:

Field	Description
`buyerReturnLineItemId`	Line item ID
`sellerReferenceNumber`	Seller’s reference
`description`	Item description
`quantity`	Quantity
`weight` / `weightUom`	Weight and unit
`value` / `valueCurrencyCode`	Value and currency
`returnReasonCode` / `returnReason`	Buyer-selected return reason
`customFieldMap`	Custom fields

Shopify Buyer Return Created

Sent when a buyer creates a return request via Shopify integration. category: shopifyBuyerCreateReturn / action: shopifyBuyerCreateReturn Key fields in shopifyReturn:

Field	Description
`shopifyReturnId`	Unique Shopify return identifier
`apiId`	Seller API ID
`referenceNumber`	Reference number
`returnRequestId`	Linked return request ID (if created)
`shipmentId`	Linked shipment ID (if created)
`returnRequestNumber` / `shipmentNumber`	Return and shipment numbers
`totalValue` / `totalValueCurrency`	Declared value and currency
`remarks`	Remarks
`labelRequestStatusCode`	Label status: `"success"` or `"fail"`
`trackingNumber`	Tracking number (on success)
`labelUrl`	Label URL (on success)
`error`	Error message (on failure)
`warehouseId`	Destination warehouse
`shipmentServiceType` / `shipmentCountryCode`	Shipping service and country
`shipmentName` / `shipmentPhone` / `shipmentEmail`	Contact details
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	Address lines
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	Address details
`costCurrencyCode` / `cost`	Shipping cost
`boxType`	Box type
`weight` / `weightUom`	Weight and unit
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	Parcel dimensions
`shopifyShopId`	Shopify shop identifier
`shopifyOrderId` / `shopifyOrderNumber` / `shopifyOrderName`	Shopify order details
`shopifyReturnStatusCode`	Shopify return status
`requestParty`	Party who initiated the return
`customFieldMap`	Custom fields

Each item in shopifyReturnLineItemList:

Field	Description
`shopifyReturnLineItemId`	Line item ID
`sellerReferenceNumber`	Seller’s reference
`description`	Item description
`quantity`	Quantity
`sku`	Product SKU
`weight` / `weightUom`	Weight and unit
`value` / `valueCurrencyCode`	Value and currency
`returnReasonCode` / `returnReason`	Buyer-selected return reason
`shopifyProductId`	Shopify product ID
`buyerNotes`	Buyer’s notes
`customFieldMap`	Custom fields

Consolidate Shipping Cost Updated

Sent when the shipping cost of a consolidated shipping order is updated. category: consolidateShippingOrderShippingFeeUpdated / action: consolidateShippingOrderShippingFeeUpdated Key fields in order:

Field	Description
`consolidateShippingOrderId`	Order identifier
`consolidateShippingOrderNumber`	Order number
`consolidateShippingOrderStatus`	Current status
`outboundWarehouseId`	Outbound warehouse
`shippingMethod`	Shipping method
`shippingFee` / `currencyCode`	Updated shipping fee and currency
`shipToContactName` / `shipToPhone` / `shipToEmail`	Ship-to contact
`shipToCompanyName`	Ship-to company
`shipToStreet1` / `shipToStreet2` / `shipToStreet3`	Ship-to address lines
`shipToCity` / `shipToState` / `shipToPostalCode` / `shipToCountry`	Ship-to address
`deliveryInstructions`	Delivery instructions

Consolidate Shipping All Packed

Sent when a warehouse has packed all inventories into boxes for a consolidated order. category: consolidateShippingOrderInventoryAllPacked / action: consolidateShippingOrderInventoryAllPacked Key fields in order:

Field	Description
`consolidateShippingOrderId`	Order identifier
`consolidateShippingOrderNumber`	Order number
`consolidateShippingOrderStatus`	Current status
`outboundWarehouseId`	Outbound warehouse
`shippingFee` / `currencyCode`	Shipping fee and currency
`shippingMethod`	Shipping method
`customFieldMap`	Custom fields
`deliveryInstructions`	Delivery instructions
`shipmentList`	List of shipments (see below)

Each item in shipmentList:

Field	Description
`consolidateShippingShipmentId`	Shipment identifier
`consolidateShippingShipmentNumber`	Shipment number
`consolidateShippingShipmentStatus`	Shipment status
`awb`	Air Waybill number
`serviceProvider`	Carrier service provider
`shipDate`	Ship date
`boxList`	List of boxes in this shipment

Each item in boxList:

Field	Description
`consolidateShippingShipmentBoxId`	Box identifier
`boxNumber`	Box number
`consolidateShippingShipmentBoxStatus`	Box status
`consolidateShippingInventoryList`	Inventories in this box

Each item in consolidateShippingInventoryList:

Field	Description
`consolidateShippingInventoryId`	Inventory identifier
`returnInventoryId`	Linked return inventory ID
`rma`	RMA value
`consolidateShippingInventoryStatus`	Inventory status

Consolidate Shipment Sent

Sent when a warehouse dispatches a consolidated shipment to a carrier. category: consolidateShippingShipmentSent / action: consolidateShippingShipmentSent Key fields in shipment:

Field	Description
`consolidateShippingShipmentId`	Shipment identifier
`consolidateShippingShipmentNumber`	Shipment number
`consolidateShippingShipmentStatus`	Current status
`awb`	Air Waybill number
`serviceProvider`	Carrier service provider
`shipDate`	Ship date
`boxList`	List of boxes (same structure as All Packed → boxList)
`consolidateShippingOrderId`	Parent order identifier
`consolidateShippingOrderNumber`	Parent order number
`consolidateShippingOrderStatus`	Parent order status
`outboundWarehouseId`	Outbound warehouse
`customFieldMap`	Custom fields

Consolidate Shipping AWB Updated

Sent when the Air Waybill number for a consolidated shipment is updated. category: consolidateShippingShipmentShipped / action: consolidateShippingShipmentShipped The shipment object follows the same structure as Consolidate Shipment Sent, with the updated awb field.

Consolidate Order Completed

Sent when all shipments in a consolidated order have been shipped. category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted The order object follows the same structure as Consolidate Shipping All Packed, including the full shipmentList with boxList and inventory details.

Consolidate Order Cancelled

Sent when a warehouse force-cancels a consolidated shipping order. category: consolidateShippingOrderCancelled / action: consolidateShippingOrderCancelled Key fields in order:

Field	Description
`consolidateShippingOrderId`	Order identifier
`consolidateShippingOrderNumber`	Order number
`consolidateShippingOrderStatus`	Current status (cancelled)
`outboundWarehouseId`	Outbound warehouse
`shippingMethod`	Shipping method
`shippingFee`	Shipping fee
`deliveryInstructions`	Delivery instructions
`customFieldMap`	Custom fields

​Overview

​Setting Up Your Webhook Endpoint

​Endpoint Requirements

​Registering Your Endpoint

​Event Delivery

​Notification Headers

​Legacy headers

​Signature Verification

​Worked Example

​Step-by-Step Verification

​Sample Code

​Retry Mechanism

​Common Body Fields

​Notification Event Reference

​Notification Payloads

​Label Result

​Warehouse Shipment Arrived (v2)

​Inventory Created

​Image Updated

​Unknown Shipment Assigned

​Recall Status Update

​Resend Status Update

​VAS Update

​Inventory Handling Complete

​Inventory Recalibrated

​Inventory Meta Updated

​RMA Updated

​SKU Updated

​Split Line Item

​Warehouse Remarks Updated

​Buyer Return Label Generated

​Shopify Buyer Return Created

​Consolidate Shipping Cost Updated

​Consolidate Shipping All Packed

​Consolidate Shipment Sent

​Consolidate Shipping AWB Updated

​Consolidate Order Completed

​Consolidate Order Cancelled

Overview

Setting Up Your Webhook Endpoint

Endpoint Requirements

Registering Your Endpoint

Event Delivery

Notification Headers

Legacy headers

Signature Verification

Worked Example

Step-by-Step Verification

Sample Code

Retry Mechanism

Common Body Fields

Notification Event Reference

Notification Payloads

Label Result

Warehouse Shipment Arrived (v2)

Inventory Created

Image Updated

Unknown Shipment Assigned

Recall Status Update

Resend Status Update

VAS Update

Inventory Handling Complete

Inventory Recalibrated

Inventory Meta Updated

RMA Updated

SKU Updated

Split Line Item

Warehouse Remarks Updated

Buyer Return Label Generated

Shopify Buyer Return Created

Consolidate Shipping Cost Updated

Consolidate Shipping All Packed

Consolidate Shipment Sent

Consolidate Shipping AWB Updated

Consolidate Order Completed

Consolidate Order Cancelled