# Returnless Webhooks

Returnless (returnless.com) is a returns management platform for e-commerce. Its webhooks notify your application when a return request is created, approved or rejected, when a return changes status or receives items, and when a shipment is created, updates or is delivered. Each webhook has its own signing secret, and every request carries a signature you can verify.

## When to Use This Skill

* How do I receive Returnless webhooks?
* How do I verify the `X-Signature` header on a Returnless webhook?
* How do I handle `return.created`, `request.approved`, or `shipment.delivered` events?
* Why is my Returnless webhook signature verification failing?
* How do I know which event a Returnless webhook is for? (It is in the `X-Event-Name` header, not the body.)

## Verification (core)

Returnless computes an HMAC-SHA256 of the **raw request body only**, keyed with the webhook's signing secret (used as its UTF-8 bytes, not decoded), and sends the **bare lowercase hex digest** in `X-Signature`. There is no prefix, no timestamp and no signed header, so there is no replay window to check.

Node:

```javascript
const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  // 64 hex chars exactly; validate before comparing
  if (!secret || typeof signatureHeader !== 'string' || !/^[0-9a-fA-F]{64}$/.test(signatureHeader)) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signatureHeader.toLowerCase()), Buffer.from(expected));
}

```

Python:

```python
import hashlib, hmac, re

def verify(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
    if not secret or not signature_header or not re.fullmatch(r"[0-9a-fA-F]{64}", signature_header):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header.lower().encode(), expected.encode())

```

In Express, read the body with `express.raw({ type: '*/*' })` so the exact bytes are verified whatever `Content-Type` is sent. Parse JSON only after the check. Reject a missing, empty, malformed or mismatched signature with `401`.

> **For complete handlers with route wiring, event dispatch, and tests**, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/returnless-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/returnless-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/returnless-webhooks/examples/fastapi/)

## Common Event Types

The event name is in the `X-Event-Name` header (`<resource>.<action>`). The JSON:API body (`data` with `id`, `resource_type`, ...) carries no event name.

| Event | Description |
| --- | --- |
| `request.created` | A return request was submitted |
| `request.approved` | A request was approved |
| `request.approved_with_manual_shipment` | Approved, with a manually created shipment |
| `request.approved_without_shipment` | Approved, with no shipment |
| `request.rejected` | A request was rejected |
| `request.status_changed` | A request changed status |
| `request.deleted` | A request was deleted |
| `return.created` | A return was created |
| `return.status_changed` | A return changed status |
| `return.notes.added` | A note was added to a return |
| `return.product.marked_as_received` | A returned product was marked as received |
| `return.product.qty_received_changed` | The received quantity of a returned product changed |
| `return.deleted` | A return was deleted |
| `shipment.created` | A shipment was created |
| `shipment.status_changed` | A shipment changed status |
| `shipment.delivered` | A shipment was delivered |
| `depreciation.created` | A depreciation was created |

> **For the full reference**, see [About webhooks](https://support.returnless.com/article/991-about-webhooks).

## Important Details

| Item | Value |
| --- | --- |
| Signature header | `X-Signature` (bare lowercase hex, no prefix) |
| Event header | `X-Event-Name` |
| Algorithm | HMAC-SHA256 of the raw body |
| Method | `POST`, `Content-Type: application/json` |
| Success | Any `2XX`; otherwise up to 10 retries with exponential backoff over 15 hours |
| Auto-disable | 24 hours after the failure email, a webhook with 5 or more failed events is disabled |
| TLS | The endpoint's certificate is validated |

## Environment Variables

```bash
RETURNLESS_WEBHOOK_SECRET=your_signing_secret   # Webhook Signing Secret from Integrations -> Webhooks

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 returnless --path /webhooks/returnless

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/returnless-webhooks/references/overview.md) - Returnless webhook concepts and payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/returnless-webhooks/references/setup.md) - Creating a webhook and getting the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/returnless-webhooks/references/verification.md) - Signature verification details