Agent skill
Returnless Webhooks Skill
Receive and verify Returnless webhooks. Use when setting up Returnless webhook handlers, debugging X-Signature verification, or handling returns management events like return.created, request.approved, or shipment.delivered.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-Signatureheader on a Returnless webhook? - How do I handle
return.created,request.approved, orshipment.deliveredevents? - 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-Nameheader, 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:
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:
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:
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_ | Approved, with a manually created shipment |
request.approved_ | 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_ | A returned product was marked as received |
return.product.qty_ | 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.
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
RETURNLESS_WEBHOOK_SECRET=your_signing_secret # Webhook Signing Secret from Integrations -> Webhooks
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 returnless --path /webhooks/returnless
Reference Materials
- references/overview.md - Returnless webhook concepts and payloads
- references/setup.md - Creating a webhook and getting the signing secret
- references/verification.md - Signature verification details