Agent skill
Paypercut Webhooks Skill
Receive and verify Paypercut webhooks. Use when setting up a Paypercut webhook endpoint, verifying the Paypercut-Signature header (HMAC-SHA256), debugging signature verification failures, or handling events like payment.succeeded, checkout_session.completed, payout.paid and account.updated.
Install this skill
npx skills add hookdeck/webhook-skills --skill paypercut-webhooks
Paypercut (paypercut.io) is a payments platform: checkout, payment intents, connected accounts, payouts and identity verification. It sends a signed JSON webhook to each endpoint you configure in the Merchant Dashboard or with the Webhooks API. An endpoint has enabled_events, a fixed api_version (v1 or v2) and an optional connect flag that also delivers events from connected accounts.
When to Use This Skill
- How do I receive Paypercut webhooks?
- How do I verify the
Paypercut-Signatureheader? - Why does my Paypercut webhook signature verification fail?
- How do I handle
payment.succeeded,checkout_orsession.completed payout.paidevents? - How do I dedupe Paypercut deliveries?
Verification (core)
Paypercut-Signature: t=<unix seconds>,v1=<hex>, where v1 is the hex HMAC-SHA256 of "<t>.<raw body>", keyed with the endpoint's secret as-is (UTF-8 bytes).
const crypto = require('crypto');
function verifyPaypercut(rawBody /* Buffer */, header, secret) {
const parts = String(header || '').split(',').map((p) => p.trim().split(/=(.*)/s));
const t = parts.find(([k]) => k === 't')?.[1];
const candidates = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!t || candidates.length === 0) return false;
const expected = Buffer.from(
crypto.createHmac('sha256', secret)
.update(Buffer.concat([Buffer.from(`${t}.`), rawBody])) // t exactly as sent, body as bytes
.digest('hex')
);
let ok = false; // any v1 entry may match (key rotation); ignore other keys such as v0
for (const c of candidates) {
if (!/^[0-9a-fA-F]{64}$/.test(c)) continue; // validate format before comparing
if (crypto.timingSafeEqual(Buffer.from(c.toLowerCase()), expected)) ok = true;
}
return ok;
}
- Sign the raw body bytes (
express.raw({ type: '*/*' }), Next.jsrequest.arrayBuffer(), FastAPIawait request.body()). NeverJSON.parseand re-stringify first. - Use
tas the exact string from the header. The key is the secret's UTF-8 bytes, not hex- or base64-decoded. - The header may hold several
v1=entries: accept if any matches. A header with not=fails. - Hex is compared case-insensitively: require exactly 64 hex characters, lowercase, then compare in constant time. Python:
hmac.compare_digeston bytes. - Missing or empty header, malformed value or mismatch:
401. Missing secret:500(fail closed). A verified body that isn't an event (typemust be a string):400. - No timestamp window by default. Hookdeck retries and replays resend the original headers and timestamp, so a fixed window would reject legitimate retries. The examples offer an opt-in
PAYPERCUT_(unset orWEBHOOK_ TOLERANCE_ SECONDS 0= off;tis Unix seconds; Paypercut suggests 300) if you want one. - Dedupe on the
Paypercut-Delivery-Idheader;Paypercut-Event-Idcarries the event id.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
HTTP Methods
Paypercut's docs don't name the HTTP method of a delivery. The examples therefore accept GET, POST, PUT, PATCH and DELETE on the webhook route, verify the signature first for every method, and treat a missing body as empty bytes (a bodyless request is verified over zero bytes, then acknowledged with 200). If Paypercut uses a method other than POST, also allow that method on the Hookdeck source (custom methods).
Event Payload and Types
Dispatch on the body's type field. The docs' payload-validation sample requires type (string) and data, and connected-account events add a top-level account. Paypercut documents no delivered sample body, so treat type as holding the identifier from the event catalogue.
| Event | Sent When |
|---|---|
checkout_ | A Checkout Session has been completed |
payment.succeeded | A payment has succeeded |
payment.failed | A payment has failed |
payment_ | A Payment Intent has been authorized |
payment_intent.captured | A Payment Intent has been captured |
payout.paid | A payout has been paid |
payout.failed | A payout has failed |
account.updated | An account has been updated |
invoice.paid | An invoice has been paid |
invoice.payment_failed | Payment for an invoice has failed |
identity.verification_ | An identity verification session has been verified |
Paypercut documents 29 events in all (account, person, tax invoice, payout and identity verification families too). See references/overview.md.
Delivery
Return 2xx only after processing: a 500 is retried (the schedule isn't documented), and acknowledging before processing can lose events.
Environment Variables
PAYPERCUT_WEBHOOK_SECRET=your_endpoint_secret # the endpoint's own signing secret
PAYPERCUT_WEBHOOK_TOLERANCE_SECONDS= # optional; unset or 0 = no timestamp window
Local Development
Paypercut can't reach localhost. Tunnel with the Hookdeck CLI (no account required):
npx hookdeck-cli listen 3000 paypercut --path /webhooks/paypercut
Use the printed URL as the endpoint URL in Paypercut.
Resources
- references/overview.md - What Paypercut webhooks are, full event list, headers
- references/setup.md - Create an endpoint and get the signing secret
- references/verification.md - Signature details, gotchas, debugging
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests