# 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_with_manual_shipment` | Approved with a manually created shipment | Track the manual shipment |
| `request.approved_without_shipment` | 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_as_received` | A returned product is marked received | Restock, trigger refund |
| `return.product.qty_received_changed` | 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

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](/docs/cli):

```bash
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](https://support.returnless.com/article/994-signing-webhook-requests) shows PHP, Python and Node versions; the PHP one uses `!==`, so prefer a constant-time comparison.

```javascript
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.

```javascript
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](/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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### 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](/webhooks/guides/implement-webhook-idempotency).

## 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](https://hookdeck.com) keeps the webhook healthy through your outages and gives each return event a verified, replayable record.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Returnless webhooks reliably in minutes.