Webhooks

CODE - A Shopify Plus Agency

March 25, 2022 10:24

It is possible to receive realtime updates from the app on certain events. When subscribed you will receive updates on an https endpoint that is defined by the merchant.

It is possible to receive updates for these events:

Request submitted (rma/submitted)
Tracking Setup (rma/tracking-setup) (3rd party integration needed)
Dropped Off (rma/dropped-off) (3rd party integration needed)
In Transit (rma/in-transit) (3rd party integration needed)
Package Received (rma/received) (3rd party integration needed)
Completed (rma/completed)

For some events a 3rd party connection is required.

Webhook anatomy

Method

The method that is used is POST

Headers

These headers are added to the webhook call:

content-type: application/json
x-returns-hmac: hash of the content signed with the secret. You can use this to verify the integrity of the call. for instance: AxsMJ8BI8JIlPa/TmiPmHr8shMYEsc2Nuj8z8bEBj5E= (below more information on how this is build up)
x-returns-topic: Event name, for instance: rma/completed

Payload

The webhook contains several fields, described below:

Field	Type	Description
promised_processing_time	Number	The number of days that it will take to process the request (set in the admin)
comment	String	Comment provided by customer
order_id	Number	The order ID
order_name	String	The order name
has_errored	Boolean	If an error occured yes or no
refund_value_cents	Number	Amount to refund in cents
return_value_cents	Number	Amount of returned products in cents
return_quantity	Number	Number of products that are returned
exchange_value_cents	Number	Amount of exchange products in cents
exchange_quantity	Number	Number of products that are exchanged
flagged_reasons	String []	Reasons why a request was flagged
timestamps	Object	Object with the following timestamps
submitted_at	String\| null	Submitted timestamp
dropped_off_at	String\| null	Dropped of timestamp
received_at	String\| null	Received (3PL) timestamp
completed_at	String \| null	When request is completed timestamp
tracking	Object	Object for tracking (only if enabled)
package_number	String\| null	The package number
provider	String\| null	The carrier provider
url	String\| null	Track and Trace URL
line_items	Object []	Line items of the return
line_item_id	Number	The order line item ID
reason	Object	Object with reason ID's (if provided)
id	String	ID of the return reason (only with 3PL integration)
reasonStrings	String []	Return reason(s)
type	String	return / exchange
third_party_data	Object	Object with 3PL data (if enabled)
return_received	Boolean	Received at 3PL?
return_condition	String \| null	Condition of the product
return_comment	String \| null	Comment of 3PL employee
return_reference	String \| null	Internal 3PL reference
return_reason_id	String \| null	The ID of the return reason
return	Object	Object with returned item
price	Number	Price in cents
product_id	Number	ID of the Product in Shopify
product_title	String	Title of the product
sku	String	SKU of the product
variant_id	Number	Variant ID in Shopify
variant_title	String	Title of the variant
exchange	Object \| null	Object with exchange item (if applicable)
price	Number	Price in cents
product_id	Number	ID of the Product in Shopify
product_title	String	Title of the product
sku	String	SKU of the product
variant_id	Number	Variant ID in Shopify
variant_title	String	Title of the variant

Below an example of a webhook that was sent by the Exchanges and Returns app.

{
  "promised_processing_time": 0,
  "comment": "",
  "order_id": 4038403162244,
  "order_name": "CODE-DEV1083",
  "has_errored": false,
  "refund_value_cents": 4900,
  "return_value_cents": 4900,
  "return_quantity": 1,
  "exchange_value_cents": 0,
  "exchange_quantity": 0,
  "flagged_reasons": [],
  "timestamps": {
    "submitted_at": "2022-03-25T09:09:17.481Z",
    "dropped_off_at": null,
    "received_at": null,
    "completed_at": "2022-03-25T10:22:11.623Z"
  },
  "tracking": {
    "package_number": null,
    "provider": "none",
    "url": null
  },
  "line_items": [
    {
      "line_item_id": 10488731631748,
      "reason": [
        {
           "id": "2"
        }
      ],
      "reasonStrings": [
        "Color not as expected"
      ],
      "type": "return",
      "third_party_data": {
        "return_received": false,
        "return_condition": null,
        "return_comment": null,
        "return_reference": null,
        "return_reason_id": null
      },
      "return": {
        "price": 4900,
        "product_id": 6741544697988,
        "product_title": "Antarctics * The Juniors",
        "sku": "8719558654390",
        "variant_id": 40087497998468,
        "variant_title": "10-11y"
      },
      "exchange": null
   }
  ]
}

HMAC Creation

The "x-returns-hmac" header is an authentication header using the HMAC SHA256 algorithm. It is a base64 encoded hash based on the payload and signed with the 'secret' that you can find in the Admin interface when you enable this feature.