Agent skill
Layerswap Webhooks Skill
Receive and verify Layerswap webhooks (crypto bridging and exchange-to-chain swap API, delivered via Svix). Use when setting up Layerswap webhook handlers, debugging svix-signature verification, or handling swap status updates like ls_transfer_pending, completed, failed, pending_refund, and refunded.
Install this skill
npx skills add hookdeck/webhook-skills --skill layerswap-webhooks
Layerswap is a crypto bridging and exchange-to-chain swap API. It pushes swap status updates to an endpoint configured per app in the Partner Dashboard, delivered through Svix, which implements Standard Webhooks. Every delivery is an HTTP POST with a JSON body and three signature headers: svix-id, svix-timestamp, and svix-signature. The body is { swap, quote, deposit_ and has no event-type field: swap.status (for example ls_transfer_pending) is the swap's lifecycle state, and swap.id is the durable key.
When to Use This Skill
- How do I receive Layerswap webhooks?
- How do I verify Layerswap webhook signatures (
svix-signature)? - How do I handle
ls_transfer_pending,completedorfailedswap updates? - How do I react to
pending_refundandrefundedswaps? - Why is my Layerswap webhook signature verification failing, or rejecting Hookdeck retries?
Verification (core)
Signed content is {svix-id}.{svix-timestamp}.{raw body}. Svix signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), base64-encodes the result, and sends one or more space-separated v1,<signature> entries. Use the official svix library, which compares in constant time. Read the svix-* headers, and when svix-id is absent fall back to the webhook-* headers (webhook-id, webhook-timestamp, webhook-signature).
import { Webhook } from 'svix'; // svix 2.x is ESM-only
const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.LAYERSWAP_WEBHOOK_SECRET).verify(rawBody, {
'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes
from svix.webhooks import Webhook, WebhookVerificationError
wh = Webhook(os.environ["LAYERSWAP_WEBHOOK_SECRET"]) # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
"webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
The webhook secret is per app and shown in the Partner Dashboard's Webhooks section. The docs don't print its format, but Svix secrets start with whsec_. Keep the full whsec_... value in LAYERSWAP_WEBHOOK_SECRET. Handlers fail closed: with the variable unset they return 500 instead of accepting anything.
Hookdeck retries and replays hit the 5-minute window
The svix library always enforces a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. Deduplicate on swap.id plus status (or svix-id) instead of relying on the timestamp.
Swap Statuses
There are no named events. The examples branch on swap.status, using the values from Layerswap's swap lifecycle docs, and acknowledge any other value with 200:
swap.status | Meaning |
|---|---|
user_transfer_pending | Swap created; waiting for the user's deposit (becomes expired after 6 hours without one) |
ls_transfer_pending | Deposit confirmed; Layerswap is executing the swap and may retry. Not final |
completed | Funds were delivered to the destination address. Terminal |
failed | For example the deposit was below the minimum. Terminal |
expired | No deposit arrived in time. Terminal |
pending_refund | Execution failed and a refund to refund_address is queued |
refunded | The refund was confirmed on-chain. Terminal |
No retry schedule, timeout or ordering is documented. Deduplicate side effects by swap.id plus status, and fetch GET /swaps/{id} before irreversible business logic. See references/overview.md for the payload and delivery rules.
Environment Variables
# Webhook secret from the Partner Dashboard (Svix format, starts with whsec_)
LAYERSWAP_WEBHOOK_SECRET=whsec_xxxxx
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 layerswap --path /webhooks/layerswap
Add the tunnel URL as an endpoint in the Partner Dashboard (app > Webhooks) and copy the webhook secret into .env. See references/setup.md.
Reference Materials
- references/overview.md - Layerswap webhook concepts, payload, swap statuses, delivery rules
- references/setup.md - Configure an endpoint in the Partner Dashboard, get the secret
- references/verification.md - Svix verification details, header fallback, manual verifier, timestamp window