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

Webhooks can be enabled directly in ReturnZap Settings > Integrations > Webhooks. You are able to specify a webhook destination URL, as well as the types of webhooks which ReturnZap will trigger.

ReturnZap supports multiple webhooks, as well as webhook signatures for added security. Please contact ReturnZap support to enable these.

Sample webhook payload

{
  "call_id": "ded4418a-0ab9-4404-bfc3-acc9f55780f0",
  "event": "return_created",
  "content": {
    "return": {
      "approval_required": false,
      "created_at": "2024-10-03T13:38:32.222378+00:00",
      "customer_address": {
        "city": "Chicago",
        "country": "US",
        "state": "IL",
        "street1": "Street Address 1",
        "street2": "",
        "zip": "60613"
      },
      "customer_email": "test@example.com",
      "customer_first_name": "ReturnZap",
      "customer_last_name": "Customer",
      "destination_address": {
        "city": "Atlanta",
        "company": "",
        "country": "US",
        "email": "email@example.com",
        "name": "ReturnZap Destination Address",
        "phone": "",
        "state": "GA",
        "street1": "Street Address 1",
        "street2": "",
        "warehouse_id": null,
        "zip": "30308"
      },
      "exchange_balance_due": null,
      "exchange_items": [],
      "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": "",
          "answers": [
            {
              "answer": "Free form question response",
              "id": "245705e7-46f0-400e-83c3-528e5b97d814",
              "is_required": false,
              "order": 5,
              "question_id": "557132b3-2ada-4da5-9cdc-a1f2d41bc2c0",
              "question_text": "This is a free form question?",
              "question_type": "LONG_TEXT",
              "response": {
                "selected_choices": [],
                "text": "Free form question response"
              }
            },
            {
              "answer": "Yes",
              "id": "2a9f48d0-7c9c-4443-b04d-97e33f71eb53",
              "is_required": false,
              "order": 6,
              "question_id": "4e8fa023-457b-4673-adb7-70630e074671",
              "question_text": "Is this a yes no question?",
              "question_type": "CHOICE",
              "response": {
                "selected_choices": [
                  {
                    "id": "6e4f8edc-2cb8-4c23-8e4c-00455032e357",
                    "text": "Yes"
                  }
                ],
                "text": ""
              }
            }
          ],
        },
        {
          "comment": "",
          "exchange_item": null,
          "id": "4601109",
          "image_url": "https://link-to-shopify-image",
          "presentment_currency": "USD",
          "presentment_discounted_amount": "11.250",
          "product_title": "Animal Zone Foam T-Rex",
          "quantity": 1,
          "return_eligibility_expires_at": "2025-12-02T04:59:59.999999+00:00",
          "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": ""
        }
      ],
      "no_shipping_required": false,
      "rejected_at": null,
      "rejection_reason": null,
      "return_item_types": [
        "REFUND"
      ],
      "return_type_labels": [
        "Refund"
      ],
      "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": ""
    }
  }