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-Signature header?
  • Why does my Paypercut webhook signature verification fail?
  • How do I handle payment.succeeded, checkout_session.completed or payout.paid events?
  • 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.js request.arrayBuffer(), FastAPI await request.body()). Never JSON.parse and re-stringify first.
  • Use t as 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 no t= fails.
  • Hex is compared case-insensitively: require exactly 64 hex characters, lowercase, then compare in constant time. Python: hmac.compare_digest on bytes.
  • Missing or empty header, malformed value or mismatch: 401. Missing secret: 500 (fail closed). A verified body that isn't an event (type must 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_WEBHOOK_TOLERANCE_SECONDS (unset or 0 = off; t is Unix seconds; Paypercut suggests 300) if you want one.
  • Dedupe on the Paypercut-Delivery-Id header; Paypercut-Event-Id carries 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.

EventSent When
checkout_session.completedA Checkout Session has been completed
payment.succeededA payment has succeeded
payment.failedA payment has failed
payment_intent.authorizedA Payment Intent has been authorized
payment_intent.capturedA Payment Intent has been captured
payout.paidA payout has been paid
payout.failedA payout has failed
account.updatedAn account has been updated
invoice.paidAn invoice has been paid
invoice.payment_failedPayment for an invoice has failed
identity.verification_session.verifiedAn 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →