⚠️ A new version of Swap Webhooks is available. We recommend switching to the latest version for full functionality
Webhooks are a way for applications to communicate automatically with each other. When an event occurs in one system (for example, a return is processed), a webhook sends real-time data to another system via an HTTP callback. This process is automated, so no manual action is needed to update information across systems.
SWAP webhooks are especially useful for keeping your app synchronised with returns information or triggering additional actions after certain events take place.
You can set up webhooks for the following events and conditions. We recommend making your webhook as specific as possible, to keep the operation efficient.
This article is for users of Returns V2. For the Returns V1 version, click here.
Event triggers
Return created – Automatically receive return information when a new return is created in the portal.
Return processed – Get notified when the RMA is finalised and processed in your dashboard.
Conditions
Returns shipping status
Options: Pre-Transit, In-Transit, Delivered
Return’s type
Options: Refund, Shop Now Credit, Shop Later Credit, Exchange, Additional Payment
How to Configure a Webhook
Go to the Integrations screen in your dashboard.
Click on New webhook.
Fill out the required fields (all required unless stated otherwise):
Webhook Name – Give your webhook an identifying name.
Description – Add a description for your convenience (for example: the objective of the webhook).
URL – The endpoint where the webhook should send data.
Event – Choose the event that will trigger the webhook.
Conditions – Optionally, choose conditions to narrow when the webhook will trigger.
After creating the first webhook, you will be shown a secret key to enable authentication. Copy it and store it securely. It cannot be revealed again.
To revoke or regenerate the key, contact our support team.
Request Construction
SWAP sends a POST request to your configured webhook URL whenever the specified event occurs.
Headers:
Content-Type: application/json
Body structure:
{ "jwt": "{signed_jwt}" }The request body contains a signed JWT under the jwt key. This encapsulates the event payload and metadata.
JWT Authentication
Authentication is handled with JSON Web Tokens (JWT). SWAP includes the signed JWT in the request body. You can verify it using your previously shared secret key. The JWT includes an expiry timestamp (exp) to prevent replay attacks.
What Return Information Will be Received
The payload includes the following fields under the return object:
Field name | Description |
return_id | Unique identifier for the return |
order_name | Name of the order |
original_order_name | Original name of the order |
order_id | Identifier for the order |
rma_number | Return Merchandise Authorisation number |
date_created | Creation date of the return |
date_updated | Last update date of the return |
submitted_at | Date the return was submitted |
type_string | String representation of the type (for example: refund) |
type | Array of types (for example: [“refund”]) |
shipping_status | Status of the shipping (for example: label-created) |
status | Status of the return (for example: shopify-returned) |
total | Total amount of the return |
store_id | Identifier for the store |
total_additional_payment | Additional payment required |
total_refund_value_customer_currency | Refund value in customer currency |
customer_currency | Customer’s currency |
customer_name | Name of the customer |
customer_email | Email of the customer |
store_name | Name of the store |
billing_address | Customer’s billing address |
shipping_address | Customer’s shipping address |
products | Details of the products in the return |
processed_by | User who processed the return |
quality_control_status | Quality control status of the return |
delivered_date | Delivery date (null if not applicable) |
tracking_number | Tracking number for the return |
Payload Example
{
"context": {
"id": "2pazxzQZ4dSI2YBeKJyOD2v8Yey",
"ts": "2024-12-01T02:13:44.327Z",
"workflow_id": "p_QPCD1K8",
"deployment_id": "d_4nsVgpeg",
"platform_version": "3.52.0",
"workflow_name": "RequestBin",
"trace_id": "2pazxyrStN6H1TxaEryykmcGnwb"
},
"event": {
"method": "POST",
"url": "https://example-webhook-url.com/",
"headers": {
"content-type": "application/json"
},
"body": {
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"payload": {
"return": {
"return_id": "hqSC23fuNgXGafRsST2woUDaTwB3",
"order_name": "24216",
"original_order_name": "24216",
"order_id": "QLXYFyJBa0Sd3yO7jjvl",
"rma_number": "1757",
"date_created": "2024-11-26T13:21:36.920Z",
"date_updated": "2024-11-26T13:21:54.866Z",
"submitted_at": "2024-11-26T13:21:40.000Z",
"type_string": "refund",
"type": ["refund"],
"shipping_status": "label-created",
"status": "shopify-returned",
"total": 39.99,
"store_id": "bsTFtu1dn0RaFeTHOZPY",
"customer_currency": "GBP",
"customer_name": "Gal Arnan",
"customer_email": "[email protected]",
"store_name": "new-store-name-3",
"billing_address": {
"name": "John Doe",
"address1": "Old Trafford",
"address2": "Stretford",
"city": "Manchester",
"postcode": "M16 0GH",
"state_province_code": "ENG",
"country_code": "GB"
},
"shipping_address": {
"name": "John Doe",
"address1": "Airport Way",
"address2": "Cool Place",
"city": "Luton",
"postcode": "LU2 9LY",
"state_province_code": "ENG",
"country_code": "GB"
},
"products": [
{
"product_id": "gid://shopify/LineItem/34019050946941",
"product_name": "20 Warm White Vintage Style Solar Festoon Lights",
"variant_name": "30",
"main_reason_text": "Changed my mind",
"item_count": 1,
"cost": 39.99,
"return_type": "refund",
"intake_reason": "no-value"
}
],
"processed_by": {
"userId": "wgetTNC3tJPNRFputzpS4nvD3qI3"
},
"tracking_number": "OT237025045GB"
},
"version": 1
}
}
}
}