Returnly Webhooks allow your systems to be notified of events when they occur in your Return Center like when a shopper has been refunded in Returnly or when a shopper has been issued return credit.

For more details on how to establish and manage Returnly webhook, please visit the webhook documentation.

Getting Started

To get started using webhooks, you need to subscribe to the 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.

Event Types

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

Returnly will 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 Details: RMA Details, Shipping Label Details, Return Line Item Details, (and Refunds for return.refunded only).

Credit Events: 

  • Credit events are useful to subscribe to if you need to update Instant Credit details displayed to a Shopper in your system.
  • Included: RMA Details and Instant Refund Voucher 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.

Return Checkout (Credit) Event Types

  • credit.issued - This event indicates that return credit has been issued to the shopper.
  • credit.used - This event indicates that return credit has been used towards a repurchase or exchange.
  • credit.disabled - This event indicates that return 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. 

Return Event Types:

Credit Event Types: 

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.
Did this answer your question?