Webhooks

A powerful communication bridge between your systems and the returns.cloud

About

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.

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.

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.

Minimalist Approach to Webhook Payloads

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:

Reduces unnecessary data transfer
Minimizes processing requirements
Aligns with returns.cloud's philosophy of minimal data requirements

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.

This design mirrors our GraphQL implementation, where you can specify exactly which data fields you need, avoiding the overhead of receiving unwanted information.

Retry Mechanism

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:

If your endpoint is unavailable or fails to respond, we don't simply discard the webhook notification
Our system will automatically attempt to redeliver the payload up to 5 times
Each retry attempt follows a progressive delay pattern to avoid overwhelming your system
This approach ensures important event notifications are not lost due to temporary connectivity issues

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.

API vs. Webhooks

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.

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.

Key Benefits

Real-time notifications: Receive immediate updates when service events occur
Reduced system load: Eliminate the need to constantly poll our API for changes
Workflow automation: Trigger automated processes based on specific service events
Data synchronization: Keep your local data in sync with our service management platform

Examples of when you might use webhooks

Keeping Your Warehouse Operations Updated

Event: return_order_parcel.status.changed

Keep your warehouse planning efficient and up-to-date by receiving notifications about return parcel status changes. These updates provide critical information about:

When parcels will arrive
Which items are included in each parcel
Which warehouse is set as the destination

The system tracks all returned shipments regardless of origin:

Customer-initiated returns
Returns using pre-printed labels
Undelivered outbound shipments that bounced back
Items not collected by customers from pick-up locations

Updating Your Customer-Facing Interface

Event: sales_order_parcel.status.changed

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.

Managing Shipping Exceptions

Event: return_order_parcel.status.changed & sales_order_parcel.status.changed

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:

Incorrect delivery addresses
Customs clearance complications
Items not collected from pick-up locations

By receiving immediate notifications about these exceptions, you can take proactive steps to resolve issues before they impact customer satisfaction.

Events

Return Order Status Change
return_order.status.changed
Return Order Parcel Status Change
return_order_parcel.status.changed
Sales Order Status Change
sales_order.status.changed
Sales Order Parcel Status Change
sales_order_parcel.status.changed
Payment Operation Status Change
payment_operation.status.changed

Example Payload

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: https://help.returns.cloud/en/article/entity-status-model

{
    	"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
    	}
    }