SWAP Webhooks

  • Updated

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": "gala@swap-commerce.com",
          "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": "[gala@swap-commerce.com](<mailto:gala@swap-commerce.com>)",
"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
}
}
}
}

Was this article helpful?

/