Setting up webhooks

Webhooks overview

Webhooks are HTTP requests which are automatically triggered within a system to send data to another system. Webhooks can be used to bring custom returns data into external systems.

For example, by ingesting webhook data, you can create a custom integration between ReturnZap and a customer service ticketing platform to enrich customer data, or into an email platform to trigger custom branded emails.

Webhook events

Return Created

ReturnZap will fire a webhook when a new return is created. The webhook payload will contain information about the customer, as well as details about the return and the items it contains.

Key information includes:

• Customer name
• Customer email
• Return methods - eg: refund, credit, exchange
• Return items, including prices and images
• Items selected in exchange, if any
• Tracking number, if a shipment was created

Note: Return Created events will be fired for all new returns, including ones which require manual review and approval

Return Updated

ReturnZap will fire a webhook when an existing return's status is updated. These webhooks fire during stage transitions - for example, from "automatically approved" to "received".

Note: Return Updated webhooks do not fire on return item actions, such as restocking or refunding

Setting up webhooks

Please contact ReturnZap support at support@returnzap.com to configure Webhooks on your account and let us know if you would like to enable the Return Created webhook, Return Updated webhook, or both.

Sample webhook payload

{
  "call_id": "ded4418a-0ab9-4404-bfc3-acc9f55780f0",
  "content": {
    "return": {
      "created_at": "2024-10-03T13:38:32.222378+00:00",
      "customer_address": {
        "city": "Chicago",
        "country": "US",
        "state": "IL",
        "street1": "Wrigley Field",
        "street2": "",
        "zip": "60613"
      },
      "customer_email": "test@example.com",
      "customer_first_name": "ReturnZap",
      "customer_last_name": "Customer",
      "id": "3063978",
      "is_archived": false,
      "items": [
        {
          "comment": "",
          "exchange_item": null,
          "id": "4601111",
          "image_url": "https://link-to-shopify-image",
          "presentment_currency": "USD",
          "presentment_discounted_amount": "14.990",
          "quantity": 1,
          "return_reason": "Other",
          "return_type": "CREDIT",
          "sku": "TOY431",
          "title": "Activity Auto",
          "title_clean": "Activity Auto",
          "value": 14.99,
          "vendor": ""
        },
        {
          "comment": "",
          "exchange_item": null,
          "id": "4601109",
          "image_url": "https://link-to-shopify-image",
          "presentment_currency": "USD",
          "presentment_discounted_amount": "11.250",
          "quantity": 1,
          "return_reason": "Changed My Mind",
          "return_type": "REFUND",
          "sku": "TOY97",
          "title": "Animal Zone Foam T-Rex - Black",
          "title_clean": "Animal Zone Foam T-Rex",
          "value": 11.25,
          "vendor": ""
        },
        {
          "comment": "",
          "exchange_item": {
            "exchange_variant_id": "45262228324603",
            "image_url": "https://link-to-shopify-image",
            "sku": "GREEN-SHIRT"
          },
          "id": "4601110",
          "image_url": "https://link-to-shopify-image",
          "presentment_currency": "USD",
          "presentment_discounted_amount": "30.000",
          "quantity": 1,
          "return_reason": "Other",
          "return_type": "EXCHANGE",
          "sku": "BLACK-SHIRT",
          "title": "The Basic T-Shirt - Black",
          "title_clean": "The Basic T-Shirt",
          "value": 30,
          "vendor": ""
        }
      ],
      "rma_form_url": "https://link-to-returnzap-rma-form.pdf",
      "rma_number": "1.1760",
      "shipment": {
        "tracking_url": ""
      },
      "shipping_method": "self",
      "shopify_order_id": "5837326942459",
      "shopify_order_number": "1760",
      "stage_id": "313387",
      "stage_label": "Test Stage 123",
      "system_stage": null,
      "tracking_number": ""
    }
  }