Skip to main content

SWAP Webhooks

G
Written by Guido Kaspers
Updated over a week ago

Webhooks are a way for applications to communicate automatically with each other. When an event occurs in one system (like a return was processed), a webhook sends real-time data to another system via an HTTP callback, like a message or notification. 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 offer to adjust the webhook to be as specific as possible, to keep the operation most effective:

  • 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:

    • Return's 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

  1. To set up Webhooks go to the Integrations screen in your dashboard

  2. Click on the “New webhook” button

  3. Fill out the required information (fields are required unless mentioned otherwise)

    1. Webhook Name - give your webhooks an identifying name to recognize what it does

    2. Description - add a description for your convenience. e.g: what is the objective of the webhook

    3. URL- what is the endpoint the webhook should send to the webhook to

    4. Event - Choose the event that will trigger the webhook

    5. Conditions - You can choose specific conditions that will apply to the events to trigger the webhooks more specifically. The conditions are optional, so in case no conditions are chosen- the event will trigger the webhook at all times

      image (3).png

    6. In case you need to revoke or regenerate the key - please ask our support team for assistance

      After creating the first webhook successfully you will be prompted with the secret key to enable authentication. Reveal and copy it, as it cannot be revealed again to keep your data safe

      image (2).png

Request Construction

Swap sends a POST request to your configured webhook URL whenever the specified event occurs.

Headers:

Content-Type: application/json

Request Body Structure:

The request body includes a signed JWT under the jwt key, encapsulating the event payload and metadata:

{
  "jwt": "{signed_jwt}"
}

Note: Sending the JWT in the request body allows stores to directly validate the payload. This aligns with common webhook implementations and simplifies integration for platforms familiar with similar methods (e.g., Shopify).

Example JWT (Decoded):

Below is an example of a decoded JWT payload:

{
  "context": {
    "id": "2pazxzQZ4dSI2YBeKJyOD2v8Yey",
    "ts": "2024-12-01T02:13:44.327Z",
    "pipeline_id": null,
    "workflow_id": "p_QPCD1K8",
    "deployment_id": "d_4nsVgpeg",
    "source_type": "COMPONENT",
    "verified": false,
    "hops": null,
    "test": false,
    "replay": false,
    "owner_id": "o_3EIK4bN",
    "platform_version": "3.52.0",
    "workflow_name": "RequestBin",
    "resume": null,
    "emitter_id": "hi_WBHKwq1",
    "external_user_id": null,
    "external_user_environment": null,
    "trace_id": "2pazxyrStN6H1TxaEryykmcGnwb"
  },
  "event": {
    "method": "POST",
    "path": "/",
    "query": {},
    "client_ip": "190.70.143.251",
    "url": "<https://example-webhook-url.com/>",
    "headers": {
      "host": "example-webhook-url.com",
      "content-length": "2000",
      "accept": "application/json, text/plain, */*",
      "content-type": "application/json",
      "user-agent": "axios/1.7.2",
      "accept-encoding": "gzip, compress, deflate, br"
    },
    "body": {
      "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzMwMTk1MzUsIm...",
      "payload": {
        "return": {
          "return_id": "hqSC23fuNgXGafRsST2woUDaTwB3",
          "order_name": "24216",
          "original_order_name": "24216",
          "order_id": "QLXYFyJBa0Sd3yO7jjvl",
          "date_created": "2024-11-26T13:21:36.920Z",
          "date_updated": "2024-11-26T13:21:54.866Z",
          "type_string": "refund",
          "type": ["refund"],
          "shipping_status": "label-created",
          "status": "shopify-returned",
          "total": 39.99,
          "store_id": "bsTFtu1dn0RaFeTHOZPY",
          "total_additional_payment": 0,
          "total_refund_value_customer_currency": 39.99,
          "customer_currency": "GBP",
          "customer_name": "Gal Arnan",
          "customer_email": "[email protected]",
          "store_name": "new-store-name-3",
          "billing_address": {
            "name": "",
            "address1": "Old Trafford",
            "address2": "Old Trafford, Stretford",
            "city": "Manchester",
            "postcode": "M16 0GH",
            "state_province_code": "ENG",
            "country_code": "GB"
          },
          "products": [{
            "product_id": "gid://shopify/LineItem/34019050946941",
            "shopify_product_id": "gid://shopify/Product/8055638786272",
            "shopify_variant_id": "gid://shopify/ProductVariant/44062152098016",
            "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
      }
    }
  }
}

JWT Authentication Explained:

Authentication is managed via JSON Web Token (JWT). Instead of sending the secret key in request headers, SWAP includes a signed JWT in the request body under the jwt key. You can verify the authenticity by decoding the JWT and validating its signature using your previously shared secret key. The JWT includes an expiration timestamp (exp) to prevent replay attacks.

What Return Information Will be Received

Webhook Payload:

Object

Field Name

Description

context

id

Unique identifier for the context.

ts

Timestamp of the event.

pipeline_id

Identifier for the pipeline, if applicable.

workflow_id

Identifier for the workflow.

deployment_id

Identifier for the deployment.

source_type

Type of the source (e.g., COMPONENT).

verified

Boolean indicating if the context is verified.

hops

Number of hops (null if not applicable).

test

Boolean indicating if it's a test event.

replay

Boolean indicating if it's a replay event.

owner_id

Identifier for the owner.

platform_version

Version of the platform.

workflow_name

Name of the workflow.

resume

Data for resumption, if applicable.

emitter_id

Identifier for the emitter.

external_user_id

External user identifier, if any.

external_user_environment

External user environment data, if any.

trace_id

Unique trace identifier.

event

method

HTTP method used (e.g., POST).

path

Request path.

query

Query parameters (if any).

client_ip

IP address of the client.

url

Full URL of the request.

headers

HTTP headers as key-value pairs.

body

Request body content.

event.body

jwt

JSON Web Token (JWT) associated with the event.

payload

Payload of the request body.

return

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.

date_created

Creation date of the return.

date_updated

Last update date of the return.

type_string

String representation of the type (e.g., refund).

type

Array of types (e.g., ["refund"]).

shipping_status

Status of the shipping (e.g., label-created).

status

Status of the return (e.g., 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

Billing address details.

billing_address

name

Name associated with the billing address.

address1

First line of the billing address.

address2

Second line of the billing address.

city

City of the billing address.

postcode

Postal code of the billing address.

state_province_code

State or province code.

country_code

Country code.

return.products

product_id

Identifier for the product.

shopify_product_id

Shopify product ID.

shopify_variant_id

Shopify variant ID.

order_number

Order number.

original_order_name

Original name of the order.

date

Date associated with the product.

product_name

Name of the product.

variant_name

Variant name of the product.

full_sku_description

Full SKU description.

sku

SKU of the product.

main_reason_id

Identifier for the main reason.

main_reason_text

Description of the main reason.

sub_reason_id

Identifier for the sub-reason.

sub_reason_text

Description of the sub-reason.

comments

Comments related to the product.

item_count

Quantity of items.

cost

Cost of the product.

return_type

Type of return (e.g., refund).

currency

Currency code.

vendor

Vendor details.

collection

Collection details.

product_alt_type

Alternative product type.

recycle_material

Material to be recycled.

grams

Weight in grams.

intake_reason

Reason for intake.

tags

Tags associated with the product.

processed_by

userId

Identifier for the user who processed the return.

return

quality_control_status

Quality control status of the return.

delivered_date

Date the product was delivered (null if not applicable).

tracking_number

Tracking number for the return.

payload Version

version

Version of the payload structure.

Payload sample

{
"context": {
"id": "2pazxzQZ4dSI2YBeKJyOD2v8Yey",
"ts": "2024-12-01T02:13:44.327Z",
"pipeline_id": null,
"workflow_id": "p_QPCD1K8",
"deployment_id": "d_4nsVgpeg",
"source_type": "COMPONENT",
"verified": false,
"hops": null,
"test": false,
"replay": false,
"owner_id": "o_3EIK4bN",
"platform_version": "3.52.0",
"workflow_name": "RequestBin",
"resume": null,
"emitter_id": "hi_WBHKwq1",
"external_user_id": null,
"external_user_environment": null,
"trace_id": "2pazxyrStN6H1TxaEryykmcGnwb"
},
"event": {
"method": "POST",
"path": "/",
"query": {},
"client_ip": "190.70.143.251",
"url": "<https://eoiytc9oj5gvb14.m.pipedream.net/>",
"headers": {
"host": "[eoiytc9oj5gvb14.m.pipedream.net](<http://eoiytc9oj5gvb14.m.pipedream.net/>)",
"content-length": "2000",
"accept": "application/json, text/plain, */*",
"content-type": "application/json",
"user-agent": "axios/1.7.2",
"accept-encoding": "gzip, compress, deflate, br"
},
"body": {
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzMwMTk1MzUsImlhdCI6MTczMzAxOTIzNSwibm9uY2UiOiI1MTVjZjVkNi01MmI5LTQ2YzktYTY5OC1mNWViODhlMWEyMWMiLCJyZXR1cm5faWQiOiJocVNDMjNmdU5nWEdhZlJzU1Qyd29VRGFUd0IzIiwib3JkZXJfaWQiOiJRTFhZRnlKQmEwU2QzeU83amp2bCIsInN0b3JlX2lkIjoiYnNURnR1MWRuMFJhRmVUSE9aUFkiLCJldmVudCI6InJldHVybkNyZWF0ZWQifQ.ZwJYoW0J6OPxntnEttC-Ww2G0gtV1n-U1iS3EmvovOg",
"payload": {
"return": {
"return_id": "hqSC23fuNgXGafRsST2woUDaTwB3",
"order_name": "24216",
"original_order_name": "24216",
"order_id": "QLXYFyJBa0Sd3yO7jjvl",
"date_created": "2024-11-26T13:21:36.920Z",
"date_updated": "2024-11-26T13:21:54.866Z",
"type_string": "refund",
"type": ["refund"],
"shipping_status": "label-created",
"status": "shopify-returned",
"total": 39.99,
"store_id": "bsTFtu1dn0RaFeTHOZPY",
"total_additional_payment": 0,
"total_refund_value_customer_currency": 39.99,
"customer_currency": "GBP",
"customer_name": "Gal Arnan",
"customer_email": "[[email protected]](<mailto:[email protected]>)",
"store_name": "new-store-name-3",
"billing_address": {
"name": "",
"address1": "Old Trafford",
"address2": "Old Trafford, Stretford",
"city": "Manchester",
"postcode": "M16 0GH",
"state_province_code": "ENG",
"country_code": "GB"
},
"products": [
{
"product_id": "gid://shopify/LineItem/34019050946941",
"shopify_product_id": "gid://shopify/Product/8055638786272",
"shopify_variant_id": "gid://shopify/ProductVariant/44062152098016",
"order_number": "",
"original_order_name": "",
"date": "",
"product_name": "20 Warm White Vintage Style Solar Festoon Lights",
"variant_name": "30",
"full_sku_description": "",
"sku": "",
"main_reason_id": "2TPRcUmXH9vis8O63BdP-",
"main_reason_text": "Changed my mind",
"sub_reason_id": "reason",
"sub_reason_text": "reason",
"comments": "",
"item_count": 1,
"cost": 39.99,
"return_type": "refund",
"currency": "",
"vendor": "",
"collection": [],
"product_alt_type": "",
"recycle_material": "",
"grams": 0,
"intake_reason": "no-value",
"tags": ""
}
],
"processed_by": {
"userId": "wgetTNC3tJPNRFputzpS4nvD3qI3"
},
"quality_control_status": "",
"delivered_date": null,
"tracking_number": "OT237025045GB"
},
"version": 1
}
}
}
}
Did this answer your question?