Configuring Webhooks and Events

Returnly Webhooks allow your systems to be notified of events when they occur for RMAs, such as when a shopper has been refunded or issued Returnly Credit.

For technical details on establishing and managing Webhooks, please review our supplemental documentation.

Getting Started

To get started using Webhooks, API access with a token must first be enabled, as is available to merchants on Returnly's Annual plan.

You need to subscribe to events by using the create endpoint and specifying the callback URL (where the event should be sent) and the event type you want to be notified of. Returnly only supports one event type per subscription.

Once the webhook subscription is established, Returnly will POST events to the specified HTTPS callback URL. Clients must respond with a status code between an HTTP 200 to 299 for the webhook to be considered successfully delivered.

Returnly will deliver events at least once, however, we do not guarantee delivery exactly once.

Events and Types

Returnly supports the following event types. Once you set up a webhook subscription, Returnly will deliver notifications when they occur with relevant details, and include the following details for the respective event types.

Return Events

• Return events are useful to subscribe to if you need to notify your ERP, 3PL, or WMS of any changes to the lifecycle of an RMA.
  • Included: RMA Details, Shipping Label Details, Return Line Item Details, and Refunds Details for return.refunded only.

Returnly Credit Events

• Subscribe to these events if you need to update Returnly Credit details displayed to a Shopper in your system.
  • Included: RMA Details and Returnly Credit Details.

Return Events Types

• return.requested - This event indicates that the shopper has requested for a return.
• return.authorized - This event indicates the shopper has been authorized to make a return.
• return.in_transit - This event indicates that return package is in transit to the final destination.
• return.delivered - This event indicates that the return package has been delivered to the final destination.
• return.item_updated - This event indicates that the merchant has updated the item quantities to reflect what was included in the return package.
• return.pending_refund - This event indicates that the return has been approved for refund, but is not yet refunded.
• return.refunded - This event indicates that the return has been refunded.
• return.canceled - This event indicates that the return has been cancelled.

Returnly Credit Event Types

• credit.issued - This event indicates that Returnly Credit has been issued to the shopper.
• credit.used - This event indicates that Returnly Credit has been used towards a repurchase or exchange.
• credit.disabled - This event indicates that Returnly Credit has been disabled.

To understand the event payloads Returnly will send, query the Returns API and include the specific details in the query parameters for respective event type.

• All Return Events (except return.refund)
  • https://api.returnly.com/returns/{RMA_Number}.json?include=shipping_labels,return_line_items
• Return Refund Events
  • https://api.returnly.com/returns/{RMA_Number}.json?include=shipping_labels,return_line_items,refunds
• Returnly Credit Event Types
  • https://api.returnly.com/returns/{RMA_Number}.json?include=instant_refund_voucher 

Retries

When a response is received outside of the HTTP 200 - 299 range, Returnly will retry the request 9 more times before skipping the event (for a total of 10 request attempts per event). Retry attempts are sent on a 5 second interval.

Failures and Webhook Subscription Deactivation

The webhook subscription will be deactivated if Returnly continually receives a response outside the HTTP 200 to 299 range. Returnly will send users with the role type "Owner" a deactivation warning e-mail if we detect that a webhook subscription is failing. This warning email is dispatched when at least one of these conditions are met:

• Over 50 consecutive webhook failures have occurred, or
• Two consecutive days have passed without receiving a 200-299 response from the subscription's delivery URL

If the issue is not resolved, Returnly will deactivate the webhook subscription when at least one of these conditions are met:

• Over 1,000 consecutive webhook failures have occurred, or
• Ten consecutive days have passed without receiving a 200-299 response from the subscription's delivery URL