Introduction

Integration & Embedding

Consumer Identification 

Rebound Events

Business Parameters

Email Templates

Outbound Events

Integrating the Widget into Your Shop

Email Communication and Templates

Item Types

Amazon Selling Partner

Webhooks

Activity Log and Data Retention

Reference: Configuration Parameters, Statuses and Rejection Reasons

Sales Force

Contacting returns.cloud Support

Introduction to Withdrawal Management

Processing Withdrawal Cases

Self-Service Portal Handover

General

Communication

Technical Concepts

Self Service Portal

Withdrawal Management

Integrations

Order Management

Sales Channel

Help Desk

Event

Logistics Provider

Fulfillment

Product Information Management

Storage

Entities & Data

Products

<h2>About</h2><p>When your system needs information about specific events that have occurred within a customer's service journey, it can subscribe to webhook topics as a mechanism for receiving near-real-time data about these events.</p><p>Webhooks in our post-purchase service management solution are useful for keeping your systems in sync with service data, or as a trigger to perform additional actions after specific events have occurred. They are also a performant alternative to continuously polling for changes to service data.</p><p>This guide provides a quick primer on when to use APIs versus webhooks, as well as key terminology and behaviors that are specific to our post-purchase service management webhooks.</p><h2>Minimalist Approach to Webhook Payloads</h2><p>Our webhook system is designed with efficiency in mind. The webhook payload sent to your defined endpoint is intentionally minimal, containing just enough information to notify you that a specific event transition has occurred. This approach:</p><ul><li>Reduces unnecessary data transfer</li><li>Minimizes processing requirements</li><li>Aligns with returns.cloud's philosophy of minimal data requirements</li></ul><p>For example, a webhook notification about a status change to "delivered" might be sufficient for your needs without requiring additional data. In cases where more details are needed, your system can use our GraphQL API to request precisely the information required—no more, no less.</p><p>This design mirrors our GraphQL implementation, where you can specify exactly which data fields you need, avoiding the overhead of receiving unwanted information.</p><h2>Retry Mechanism</h2><p>We understand that endpoint availability is not guaranteed 100% of the time. To ensure reliable message delivery, our webhook system includes a robust retry mechanism:</p><ul><li>If your endpoint is unavailable or fails to respond, we don't simply discard the webhook notification</li><li>Our system will automatically attempt to redeliver the payload up to 5 times</li><li>Each retry attempt follows a progressive delay pattern to avoid overwhelming your system</li><li>This approach ensures important event notifications are not lost due to temporary connectivity issues</li></ul><p>By combining minimal payloads with reliable delivery mechanisms, our webhook system provides an efficient and dependable way to keep your systems synchronized with post-purchase service events.</p><h2>API vs. Webhooks</h2><p>APIs require your system to make requests to our service at regular intervals to check for updates, which is known as polling. This approach is effective when you need to retrieve data on demand, but it can be inefficient for tracking real-time events.</p><p>Webhooks, on the other hand, allow our service to notify your system immediately when specific events occur. This "push" model ensures timely updates without the overhead of frequent polling, making webhooks ideal for event-driven workflows in your post-purchase service processes.</p><h3>Key Benefits</h3><ul><li><strong>Real-time notifications</strong>: Receive immediate updates when service events occur</li><li><strong>Reduced system load</strong>: Eliminate the need to constantly poll our API for changes</li><li><strong>Workflow automation</strong>: Trigger automated processes based on specific service events</li><li><strong>Data synchronization</strong>: Keep your local data in sync with our service management platform</li></ul><h2>Examples of when you might use webhooks</h2><h3><span style="color:rgb(0,0,0);">Keeping Your Warehouse Operations Updated</span></h3><p>Event: <code>return_order_parcel.status.changed</code></p><p>Keep your warehouse planning efficient and up-to-date by receiving notifications about return parcel status changes. These updates provide critical information about:</p><ul><li>When parcels will arrive</li><li>Which items are included in each parcel</li><li>Which warehouse is set as the destination</li></ul><p>The system tracks all returned shipments regardless of origin:</p><ul><li>Customer-initiated returns</li><li>Returns using pre-printed labels</li><li>Undelivered outbound shipments that bounced back</li><li>Items not collected by customers from pick-up locations</li></ul><h3><span style="color:rgb(0,0,0);">Updating Your Customer-Facing Interface</span></h3><p>Event: <code>sales_order_parcel.status.changed</code></p><p><span style="color:rgb(0,0,0);">Just as you can trigger processes for incoming returns, you can also leverage webhooks for outbound shipment events. Our customers most commonly use the "delivered" status update to refresh their shop frontend, providing customers with real-time delivery information without manual intervention.</span></p><h3><span style="color:rgb(0,0,0);">Managing Shipping Exceptions</span></h3><p>Event: <code>return_order_parcel.status.changed</code> &amp; <code>sales_order_parcel.status.changed</code></p><p>Parcels may encounter operational exceptions during transport—both outbound to your customers and as returns coming back to your warehouse. Webhooks allow you to respond quickly to issues such as:</p><ul><li>Incorrect delivery addresses</li><li>Customs clearance complication</li><li>Items not collected from pick-up locations</li></ul><p>By receiving immediate notifications about these exceptions, you can take proactive steps to resolve issues before they impact customer satisfaction.</p><h2>Events</h2><ul><li>Return Order Status Change&nbsp;&nbsp;<br><code>return_order.status.changed</code></li><li>Return Order Parcel Status Change&nbsp;&nbsp;<br><code>return_order_parcel.status.changed</code></li><li>Sales Order Status Change&nbsp;&nbsp;<br><code>sales_order.status.changed</code></li><li>Sales Order Parcel Status Change&nbsp;&nbsp;<br><code>sales_order_parcel.status.changed</code></li><li>Payment Operation Status Change&nbsp;&nbsp;<br><code>payment_operation.status.changed</code></li></ul><h2>Entity Creation Events</h2><p>In addition to notifying you about transitions between existing statuses, our webhook system also fires a notification when an entity is first created. This lets your system react to brand-new entities at the very start of their lifecycle, rather than waiting for a later status change.</p><p>A creation event is expressed as a status transition where there is no prior state. In this case the <code>oldStatus</code> is set to <code>"null"</code>, representing the absence of a previous status, and the <code>newStatus</code> reflects the entity's initial status.</p><p>Creation events are available for all five webhook event types:</p><ul><li><code>return_order.status.changed</code></li><li><code>return_order_parcel.status.changed</code></li><li><code>sales_order.status.changed</code></li><li><code>payment_operation.status.changed</code></li></ul><p>The example below shows a return order creation event, where the status transitions from <code>"null"</code> to <code>"created"</code>. As with all our webhooks, the payload is intentionally minimal, so you can retrieve any additional details via our GraphQL API when needed.</p><pre><code class="language-typescript">{
      "event": "return_order.status.changed",
      "oldStatus": "null",
      "newStatus": "created",
      "returnOrder": {
        "number": "100284",
        "uuid": "36a0e99b-99e3-4dd6-b390-9d2d9fe691d3-c19cd7fd-a199-4ddc-8898-bcdc405405d0",
        "externalId": null
      }
    }</code></pre><p>
</p><h2>Example Payload</h2><p>Below is a sample webhook notification that illustrates a return order status change. In this example, the status has transitioned from "approved" (indicating the return was initially accepted) to "option_selected" (indicating the customer has now chosen their preferred return method). This minimal payload provides just enough information to alert your system about the status change, allowing you to decide whether additional details should be retrieved via our GraphQL API. For comprehensive information about all possible status values and their meanings in the workflow, please refer to our status documentation at: <a href="https://help.returns.cloud/en/article/entity-status-model">https://help.returns.cloud/en/article/entity-status-model</a></p><p>&nbsp; &nbsp;&nbsp;</p><pre><code class="language-typescript">{
        	"event":"return_order.status.changed",
        	"oldStatus":"approved",
        	"newStatus":"option_selected",
        	"returnOrder": 
        	{
        		"number":"100004",
        		"uuid":"90aabf83-d23c-4792-b483-2546b8041379-071569a0-99d9-43d2-a466-9f82408d1ae0",
        		"externalId":null
        	}
        }</code></pre><p>
</p><h3>&nbsp;</h3><h3>payment_operation.status.changed</h3><p>&nbsp; &nbsp;&nbsp;</p><pre><code class="language-typescript">{
      "event": "payment_operation.status.changed",
      "oldStatus": "pending",
      "newStatus": "paid",
      "paymentOperation": {
        "uuid": "a6e52bd6-adda-4a63-b232-0a59dc42209-1a77a75e-c44c-48ec-9efd-888a0789a243",
        "type": "refund",
        "remunerationType": "bonus_points",
        "intent": "compensation",
        "amount": "1896",
        "value": "632.98",
        "currency": "EUR",
        "processedAt": "2025-12-04T12:00:00+00:00",
        "paymentOperationSubjects": [
          {
            "returnOrder": {
              "number": "211204",
              "uuid": "ac661a41-27fe-4aaa-9e4d-b2fe204c8031-990bedd3-296c-4166-b1f7-28fba5aa32e1",
              "externalId": null
            }
          }
        ]
      }
    }</code></pre><p>
</p><h3>sales_order.status.changed</h3><p>&nbsp; &nbsp;&nbsp;</p><pre><code class="language-typescript">{
      "event": "sales_order.status.changed",
      "oldStatus": "transit",
      "newStatus": "delivered",
      "salesOrder": {
        "uuid": "6cd375c1-b81f-43db-8caa-0eeb7bea5634-b0180452-754e-41f3-af6f-40b745007e1a",
        "externalId": "5f213c30be3bb",
        "number": "67030683"
      }
    }</code></pre><p>
</p><h3>return_order.status.changed</h3><p>&nbsp; &nbsp;&nbsp;</p><pre><code class="language-typescript">{
      "event": "return_order.status.changed",
      "oldStatus": "in_process",
      "newStatus": "finished",
      "returnOrder": {
        "uuid": "a6e52bd6-adda-4aa3-b232-0a59dc355d09-1a77a75e-c44c-48ec-9efd-888a0789a243"
      }
    }</code></pre><p>
</p><h3>return_order_parcel.status.changed</h3><p>&nbsp; &nbsp;&nbsp;</p><pre><code class="language-typescript">{
      "event": "return_order_parcel.status.changed",
      "oldStatus": "finished",
      "newStatus": "transit",
      "returnOrderParcel": {
        "uuid": "c04f34c7-fd50-426f-94cb-1c6f4ea4ccf4-308eb7b5-388c-4526-99db-35a7e200051f"
      }
    }</code></pre><p>
</p><p>&nbsp;</p>

Was this article helpful?

You recently requested to reset your password for your account. Use the button below to reset it. This password reset is only valid for the next 24 hours.

If you’re having trouble with the button above, copy and paste the URL below into your web browser.

Please check your email for instructions to reset your password.

Check your email

Enter your email address and we will send you instructions to reset your password.

returns.cloud Help Center

Self Service Portal

Technical Concepts

Featured Articles

Webhooks

Introduction to Withdrawal Management