Gareth Wilson Gareth Wilson

Guide to Returnless Webhooks: Features and Best Practices

Published


Returnless is a returns management platform for online shops: customers request a return through a branded portal, the shop approves or rejects it, labels and shipments are arranged, and the warehouse records what comes back. Refunds, stock and support tickets live in other systems, so Returnless webhooks are how an ERP, WMS or helpdesk keeps up with each return as it moves.

This guide covers Returnless's request, return and shipment events, the separate test-mode webhooks, verifying X-Signature, and the retry and auto-disable rules.

What are Returnless webhooks?

Webhooks are set up in the Returnless panel under Integrations > Webhooks. Each one has an endpoint, a list of events, a signing secret and a test-mode switch: a test-mode webhook receives events only from return forms in test mode, and a live webhook only from live forms.

When a selected event happens, Returnless sends a POST with Content-Type: application/json. The event name is in the X-Event-Name header, for example return.created; the body is a JSON:API-style resource under data and doesn't repeat the name.

Every request is signed. X-Signature holds a hex HMAC-SHA256 of the raw body, keyed with that webhook's secret.

Returnless webhook features

FeatureDetails
ConfigurationPanel Integrations > Webhooks
Test modePer webhook: test forms only, or live forms only
Signaturehex HMAC-SHA256
Signature headerx-signature
Signed contentThe raw request body
KeyOne signing secret per webhook
BodyJSON, resource under data
Event routingHeader field X-Event-Name
SuccessAny 2XX
RetriesUp to 10, exponential backoff over 15 hours
Auto-disable5+ failed events, 24 hours after the failure email
TLSEndpoint certificate is validated

Events and payloads

EventTriggered WhenCommon Use Cases
request.createdA return request is submittedOpen a ticket, notify the warehouse
request.approvedA request is approvedIssue a label, notify the customer
request.approved_with_manual_shipmentApproved with a manually created shipmentTrack the manual shipment
request.approved_without_shipmentApproved with no shipmentSkip logistics, go to refund
request.rejectedA request is rejectedNotify support
request.status_changedA request changes statusKeep an external status in sync
request.deletedA request is deletedRemove it from downstream systems
return.createdA return is createdStart receiving and refund flows
return.status_changedA return changes statusStatus sync
return.notes.addedA note is added to a returnSurface notes in your helpdesk
return.product.marked_as_receivedA returned product is marked receivedRestock, trigger refund
return.product.qty_received_changedThe received quantity changesAdjust inventory
return.deletedA return is deletedCleanup
shipment.createdA shipment is createdStore tracking number
shipment.status_changedA shipment changes statusTracking updates
shipment.deliveredA shipment is deliveredExpect the parcel at the warehouse
depreciation.createdA depreciation is createdAdjust refund amounts

These are the 17 events in Returnless's supported list. Returnless publishes the names without descriptions, so the "Triggered When" column is read from the names; confirm the exact trigger for any event your business logic depends on.

Event Payload Structure

data is the resource the event concerns. For a return it includes nested includes.customer, notes and shipments. Returnless's one example body is generated from its OpenAPI schema, with every value shown as a type name such as "string", so capture real deliveries for realistic fixtures.

Setting up Returnless webhooks

Prerequisites

  • A Returnless account with access to the Integrations section of the panel
  • A publicly reachable HTTPS endpoint with a valid certificate

Create the Webhook and Get Your Signing Secret

  1. Log in to your Returnless panel and open Integrations > Webhooks.
  2. Click Add endpoint and set:
    • Is enabled: on, to deliver events.
    • Test mode: on for test-mode forms, off for live forms.
    • Endpoint: your URL, for example https://example.com/webhooks/returnless.
    • Webhook Signing Secret: the secret used to sign requests, unique to this webhook.
    • Webhook description: an internal label.
    • Events: the events that should trigger this webhook.
  3. Save, then put the signing secret in WEBHOOK_SECRET.

Because test mode is a property of the webhook, you'll typically have two: a test one pointing at staging and a live one pointing at production, each with its own secret.

Re-enabling a Disabled Webhook

If a webhook was disabled after repeated failures, fix your endpoint, then edit the webhook under Integrations > Webhooks and set it to enabled. This resets the failed-events counter.

Test a delivery

Start a local receiver and forward requests with the Hookdeck CLI:

npx hookdeck-cli listen 3000 returnless --path /webhooks/returnless

Create a test-mode webhook with the CLI's URL, then submit a return through a test-mode form. Check X-Event-Name and the shape of data.

Securing Returnless webhooks

Compute HMAC-SHA256 of the full raw body with the webhook's signing secret, hex-encode it, and compare it with X-Signature in constant time. The header is the digest alone, with no sha256= prefix. Returnless's signing article shows PHP, Python and Node versions; the PHP one uses !==, so prefer a constant-time comparison.

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

The handler routes on the header and deduplicates on the event name, the resource ID and a hash of the body, since Returnless sends no delivery ID.

const express = require('express');

function createReturnlessApp({ claim, erp, warehouse, helpdesk }) {
  const app = express();
  app.post('/webhooks/returnless', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    const eventName = req.headers['x-event-name'];
    let parsed;
    try {
      parsed = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
    const { data } = parsed;
    if (typeof eventName !== 'string' || !data || typeof data !== 'object') {
      return res.sendStatus(400);
    }
    try {
      const bodyHash = crypto.createHash('sha256').update(req.body).digest('hex');
      if (!(await claim(`${eventName}:${data.id}:${bodyHash}`))) return res.sendStatus(200);
      if (eventName.startsWith('request.')) await helpdesk.syncRequest(eventName, data);
      else if (eventName.startsWith('return.product.')) await warehouse.updateReceipt(eventName, data);
      else if (eventName.startsWith('return.')) await erp.syncReturn(eventName, data);
      else if (eventName.startsWith('shipment.')) await warehouse.trackShipment(eventName, data);
      else console.log('Unhandled Returnless event', eventName);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

Only the body is signed, so a replay of a captured request verifies. The dedup key prevents it from changing anything twice.

When a Returnless source receives a request, Hookdeck verifies X-Signature over the raw body with your signing secret and responds 200 to Returnless regardless. A mismatch is recorded as failed verification and not forwarded, and since Returnless always gets a success, failures on your side never push the webhook towards being disabled. There's no timestamp check.

Make Returnless webhooks production-ready. Hookdeck Event Gateway keeps Returnless webhooks from being disabled during outages, verifies each event, and routes requests, returns and shipments to the systems that own them.

Returnless webhook limitations and pain points

Auto-disable after failures

The Problem: Return updates stop arriving, and nobody notices until customers complain about refunds.

Why It Happens: After 10 retries over 15 hours, an event is marked failed and an email is sent. If a webhook has 5 or more failed events 24 hours after that email, it's disabled.

Workarounds:

  • Send the failure email to a monitored address.
  • Re-enable the webhook promptly once the endpoint is fixed.

How Hookdeck Can Help: Hookdeck always acknowledges Returnless, so failures in your service don't count against the webhook. Events are stored and retried to your service separately.

Event names without descriptions

The Problem: It's unclear exactly when some events fire, for example how request.status_changed relates to request.approved.

Why It Happens: Returnless lists event names but doesn't describe them on the main webhook pages.

Workarounds:

  • Subscribe a test-mode webhook to everything, run a return through each path, and note which events fire.

How Hookdeck Can Help: Hookdeck's request log records each event's header and body in order, which documents the sequence for you.

No delivery ID

The Problem: Retries can trigger duplicate refunds or restocks.

Why It Happens: Returnless doesn't send a delivery or event ID.

Workarounds:

  • Combine X-Event-Name, the resource ID and a body hash.
  • Make receipt and refund operations check current state first.

How Hookdeck Can Help: Hookdeck deduplication can drop identical requests before they reach your service.

Separate test and live webhooks

The Problem: Test returns appear in production systems, or live returns never reach staging.

Why It Happens: A webhook receives either test-mode or live events, never both, and each has its own secret.

Workarounds:

  • Point test and live webhooks at different environments with separate secrets.

How Hookdeck Can Help: Separate Hookdeck sources for test and live keep the secrets apart and make it obvious which traffic is which.

Best practices

Read the event from the header

The body doesn't name the event. Always use X-Event-Name.

Use a valid certificate

Returnless validates the endpoint's TLS certificate, so self-signed certificates fail.

Acknowledge quickly

Returnless doesn't state a timeout. Store the request, return 2XX, and update your ERP or WMS from a queue, as described in our asynchronous processing guide.

Guard stock and refund changes

return.product.qty_received_changed and refund-related events affect money and inventory. Record what you applied for each event, following the idempotency guide.

Conclusion

Returnless webhooks give your other systems a live view of every return request, return and shipment, with a straightforward hex HMAC on the body. Plan for the auto-disable rule, separate test and live webhooks, event names without descriptions, and the lack of a delivery ID.

Hookdeck Event Gateway keeps the webhook healthy through your outages and gives each return event a verified, replayable record.

Get started with Hookdeck for free and handle Returnless webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.