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-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:

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.

EventDescription
request.createdA return request was submitted
request.approvedA request was approved
request.approved_with_manual_shipmentApproved, with a manually created shipment
request.approved_without_shipmentApproved, with no shipment
request.rejectedA request was rejected
request.status_changedA request changed status
request.deletedA request was deleted
return.createdA return was created
return.status_changedA return changed status
return.notes.addedA note was added to a return
return.product.marked_as_receivedA returned product was marked as received
return.product.qty_received_changedThe received quantity of a returned product changed
return.deletedA return was deleted
shipment.createdA shipment was created
shipment.status_changedA shipment changed status
shipment.deliveredA shipment was delivered
depreciation.createdA depreciation was created

For the full reference, see About webhooks.

Important Details

ItemValue
Signature headerX-Signature (bare lowercase hex, no prefix)
Event headerX-Event-Name
AlgorithmHMAC-SHA256 of the raw body
MethodPOST, Content-Type: application/json
SuccessAny 2XX; otherwise up to 10 retries with exponential backoff over 15 hours
Auto-disable24 hours after the failure email, a webhook with 5 or more failed events is disabled
TLSThe 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →