> For the complete documentation index, see [llms.txt](https://parcelwill-returns.gitbook.io/help-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://parcelwill-returns.gitbook.io/help-center/settings/returns-webhooks.md). # Returns webhooks **Webhooks** ```json { "rma": "R2024010100000000001", "shop_domain": "return-demo.myshopify.com", "original_order_no": "#1001", "return_order_no": "#1001-R1", "return_status": "Approved", "currency": "USD", "updated_time": 1736247039, "created_time": 1736247039, "customer": { "name": "Danny", "email": "Returns@channelwill.com" }, "return_solution": { "solution": "Refund to original payment method", "total_refund": 100, "actual_refund": 50, "exchange_items": [ { "exchange_item_id": 1001, "name": "Nike C1TY", "sku": "short", "price": 60.52, "quantity": 1 } ], "exchange_order_no": "", "customer_have_paid": 0 }, "return_shipping_method": { "method": "Label", "carrier": "USPS", "tracking_no": "USPS1234567890", "return_shipment_status": "in transit", "currency": "USD", "shipping_fee": 20, "list": [ { "date": "2025-01-02 09:30:00", "details": "NORTH HOUSTON, TX", "checkpoint_status": "in transit", "status_description": "Arrived at USPS Origin Facility" }, { "date": "2025-01-01 07:30:00", "details": "HOUSTON, TX", "checkpoint_status": "pending", "status_description": "Shipping Label Created" } ] }, "return_process_status": ["Refunded"], "return_items": [ { "name": "Nike C1TY", "sku": "short", "price": 60.52, "quantity": 1, "return_reason": "Don't like", "reason_description": "", "provide_proof": ["https://xxx/image.png"], "exchange_item_id": 1001 } ] } ``` **Step 1: Extract signatures from the header** Get the `x-return-hmac-sha256` information in the request header as signatures **Step 2: Get client secret and request body** Get Client secret by Returns & Exchange Get request body **Step 3: Determine the expected signature** Compute an HMAC with the SHA256 hash function. Use the lient secret as the key, and use the request body as the message. **Step 4: Compare the signatures** Compare the signature in the header to the expected signature. **Event delivery behaviors** **Retry behavior** If we detect a push anomaly, we will re-push using exponential backoff, and will re-push the webhook up to 8 times **Example** PHP ```php // Extract signatures from the header $xReturnHmacSha256 = $_SERVER['HTTP_X_RETURN_HMAC_SHA256']; // Receive data $body = file_get_contents('php://input'); // Client secret by Returns & Exchange $signatures = 'pprs_*************0a575cf8bfd158'; // Determine the expected signature $expected_signature= base64_encode(hash_hmac('sha256', $body, $signatures, true)); // Compare the signatures if ($expected_signature == $signatures ) { // sent by returns } else { // not sent by returns } ``` GO ```go package main import ( "crypto/hmac" "crypto/sha256" "encoding/base64" "fmt" "io/ioutil" "net/http" ) func main() { http.HandleFunc("/", handleRequest) http.ListenAndServe(":8080", nil) } func handleRequest(w http.ResponseWriter, r *http.Request) { // Extract signatures from the header xReturnHmacSha256 := r.Header.Get("X-Return-Hmac-Sha256") // Receive data body, err := ioutil.ReadAll(r.Body) if err != nil { http.Error(w, "Unable to read body", http.StatusBadRequest) return } defer r.Body.Close() // Client secret by Returns & Exchange signatures := "pprs_*************0a575cf8bfd158" // Determine the expected signature expectedSignature := computeHMAC(body, signatures) // Compare the signatures if expectedSignature == xReturnHmacSha256 { fmt.Fprintln(w, "sent by returns") } else { fmt.Fprintln(w, "not sent by returns") } } func computeHMAC(data []byte, key string) string { h := hmac.New(sha256.New, []byte(key)) h.Write(data) return base64.StdEncoding.EncodeToString(h.Sum(nil)) } ``` | Param | Type | Descriptive | Example | | ------------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | rma | string | RMA no. | R2024010100000000001 | | shop\_domain | string | Shop myshopify domain | return-demo.myshopify.com | | original\_order\_no | string | Original order no. | #1001 | | return\_order\_no | string | Return order no. | #1001-R1 | | return\_status | string |

Return status:
Pending review,Approved,Resolved,Rejected

| Approved | | currency | string | Using return order currency | USD | | updated\_time | integer | Updated time | 1736247039 | | created\_time | integer | Return created time | 1736247039 | | customer | object | Customer message | | | customer.name | string | Customer name | Danny | | customer.email | string | Customer email | | | return\_solution | object | Return solution | | | return\_solution.solution | string |

Type solution name:
Refund to original payment method,Refund to store gift card,Refund to store discount,Variant exchange,Exchange for different items,Refund to store credit

| Refund to original payment method | | return\_solution.total\_refund | float | Total refund | 100 | | return\_solution.actual\_refund | float |

Actual refund

| 50 | | return\_solution.exchange\_items | array | Exchange items | \[] | | return\_solution.exchange\_items\[].exchange\_item\_id | integer | Exchange item id: If the parameter is 0, it means there is no corresponding product | 1001 | | return\_solution.exchange\_items\[].name | string | Name | Nike C2TY | | return\_solution.exchange\_items\[].sku | string | SKU | short | | return\_solution.exchange\_items\[].price | float | Price | 70.52 | | return\_solution.exchange\_items\[].quantity | integer | Quantity | 1 | | return\_solution.exchange\_order\_no | string | Exchange order no. | #1002 | | return\_solution.customer\_have\_paid | float | Customer have paid | 10.52 | | return\_shipping\_method | object | Return shipping method | | | return\_shipping\_method.method | string |

Type method name:
Label,Pickup,Ship on your own, Green returns

| Label | | return\_shipping\_method.carrier | string | Carrier name | USPS | | return\_shipping\_method.tracking\_no | string | Tracking no. | USPS1234567890 | | return\_shipping\_method.return\_shipment\_status | string |

Return shipment status:
pending,info received,in transit,out for delivery,delivered,exception,failed attempt,expired

| In transit | | return\_shipping\_method.currency | string | Store currency | USD | | return\_shipping\_method.shipping\_fee | float | Shipping fee | 20 | | return\_shipping\_method.list | array \| null | | | | return\_shipping\_method.list\[].date | string | Shipment point date | 2025-01-01 10:00:00 | | return\_shipping\_method.list\[].details | string | Shipment details | | | return\_shipping\_method.list\[].checkpoint\_status | string |

Shipment point status:
pending,info received,in transit,out for delivery,delivered,exception,failed attempt,expired

| in transit | | return\_shipping\_method.list\[].status\_description | string | Status description | | | return\_process\_status | array \| null |

Return process status:

Pending refund,Refund failed,Refund processing,Refunded,Pending creation of exchange order,Exchanged,Pending marking as received,Partially received,Received,Pending restock,Partially restocked,Restocked

| \["Pending refund"] | | return\_items | array \| null | Return items | | | return\_items\[].name | string | Name | Nike C1TY | | return\_items\[].sku | string | SKU | short | | return\_items\[].price | float | Price | 60.52 | | return\_items\[].quantity | integer | Quantity | 1 | | return\_items\[].return\_reason | string | Return reason | Don't like | | return\_items\[].reason\_description | string | Return description | | | return\_items\[].provide\_proof | array \| null | Provide proof | \[""] | | return\_items\[].exchange\_item\_id | integer | Return exchange item ID (only variation exchange): If the parameter is 0, it means there is no corresponding product | 1001 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://parcelwill-returns.gitbook.io/help-center/settings/returns-webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.