Guide to Returnless Webhooks: Features and Best Practices
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
| Feature | Details |
|---|---|
| Configuration | Panel Integrations > Webhooks |
| Test mode | Per webhook: test forms only, or live forms only |
| Signature | hex HMAC-SHA256 |
| Signature header | x-signature |
| Signed content | The raw request body |
| Key | One signing secret per webhook |
| Body | JSON, resource under data |
| Event routing | Header field X-Event-Name |
| Success | Any 2XX |
| Retries | Up to 10, exponential backoff over 15 hours |
| Auto-disable | 5+ failed events, 24 hours after the failure email |
| TLS | Endpoint certificate is validated |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
request.created | A return request is submitted | Open a ticket, notify the warehouse |
request.approved | A request is approved | Issue a label, notify the customer |
request.approved_ | Approved with a manually created shipment | Track the manual shipment |
request.approved_ | Approved with no shipment | Skip logistics, go to refund |
request.rejected | A request is rejected | Notify support |
request.status_changed | A request changes status | Keep an external status in sync |
request.deleted | A request is deleted | Remove it from downstream systems |
return.created | A return is created | Start receiving and refund flows |
return.status_changed | A return changes status | Status sync |
return.notes.added | A note is added to a return | Surface notes in your helpdesk |
return.product.marked_ | A returned product is marked received | Restock, trigger refund |
return.product.qty_ | The received quantity changes | Adjust inventory |
return.deleted | A return is deleted | Cleanup |
shipment.created | A shipment is created | Store tracking number |
shipment.status_changed | A shipment changes status | Tracking updates |
shipment.delivered | A shipment is delivered | Expect the parcel at the warehouse |
depreciation.created | A depreciation is created | Adjust 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
- Log in to your Returnless panel and open Integrations > Webhooks.
- 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.
- 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_ 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.