Gareth Wilson Gareth Wilson

Guide to Paypercut Webhooks: Features and Best Practices

Published


Paypercut is a payments platform offering hosted checkout, payment intents, invoicing, payouts, connected accounts for platforms and identity verification. If that sounds like Stripe's product list, its webhooks will feel familiar too: per-endpoint event lists, a fixed API version, a Connect option for platform accounts, and a t=...,v1=... signature header. Webhooks are how your app learns that a checkout completed, a payout failed or a user passed identity verification.

This guide covers configuring Paypercut endpoints, the 29 documented events, verifying Paypercut-Signature, and the parts of delivery the docs leave unspecified.

What are Paypercut webhooks?

Each webhook endpoint, created in the Merchant Dashboard or through the Webhooks API, has three settings that shape what it receives:

  • enabled_events: the exact event identifiers to send. Wildcards such as * aren't accepted.
  • api_version: v2 (recommended) or v1 (legacy, and the default if you omit it). This decides the shape of Checkout Session and Payment Intent payloads, and can't be changed after creation.
  • connect: when true, the endpoint also receives events from accounts connected to your platform, with a top-level account field naming the account.

Deliveries are JSON over HTTPS, with Paypercut-Event-Id identifying the event and Paypercut-Delivery-Id identifying the attempt. Paypercut-Signature carries a Unix timestamp and a hex HMAC-SHA256 over the timestamp and body.

Paypercut webhook features

FeatureDetails
ConfigurationMerchant Dashboard, or POST /v1/webhooks
Event selectionenabled_events, exact identifiers only
Payload versionapi_version per endpoint, fixed at creation
Connected accountsconnect: true, with top-level account
Signaturehex HMAC-SHA256
Signature headerpaypercut-signature (t=<unix>,v1=<hex>)
Signed content<t>.<raw body>
KeyThe endpoint's own secret
BodyJSON
Event routingBody field type
IDsPaypercut-Event-Id, Paypercut-Delivery-Id
RetriesOn 5xx; schedule undocumented
HTTP methodNot documented

Events and payloads

EventTriggered WhenCommon Use Cases
checkout_session.completedA Checkout Session has been completedFulfil an order
payment.succeededA payment has succeededMark an order as paid
payment.failedA payment has failedNotify the customer, retry
payment_intent.authorizedA Payment Intent has been authorizedCapture when ready
payment_intent.capturedA Payment Intent has been capturedRecord captured funds
payout.paidA payout has been paidReconcile settlements
payout.failedA payout has failedAlert finance
account.updatedAn account has been updatedRefresh a connected account's status
invoice.paidAn invoice has been paidExtend a subscription
invoice.payment_failedPayment for an invoice has failedDunning
identity.verification_session.verifiedAn identity verification session has been verifiedUnlock a verified user

All Documented Events (29)

  • Checkout: checkout_session.completed
  • Payment: payment.succeeded, payment.failed
  • Payment Intent: payment_intent.authorized, payment_intent.captured
  • Account: account.created, account.updated, account.capability.requested, account.capability.updated, account.external_account.created, account.external_account.updated
  • Person: person.created, person.updated, person.deleted
  • Invoice: invoice.paid, invoice.payment_failed
  • Tax Invoice: tax_invoice.finalized, tax_invoice.available
  • Payout: payout.created, payout.updated, payout.paid, payout.failed, payout.canceled
  • Identity Verification: identity.verification_session.created, .processing, .requires_input, .verified, .canceled, .redacted (each prefixed identity.verification_session)

Paypercut publishes no delivered event body. Its own validation sample requires a string type and a data object, and the event catalogue adds account for connected-account events, which is the basis for routing on type. The fields inside data depend on the resource and, for checkout sessions and payment intents, on the endpoint's api_version. Capture real deliveries before writing parsers.

tax_invoice.finalized fires before the PDF exists; wait for tax_invoice.available before downloading it.

Setting up Paypercut webhooks

Prerequisites

  • A Paypercut account with access to the Merchant Dashboard, or an API key for the Webhooks API
  • A public HTTPS endpoint

Create an Endpoint

  1. In the Merchant Dashboard, add a webhook endpoint, or call POST /v1/webhooks.
  2. Set the URL and the enabled_events you handle, spelled exactly as listed.
  3. Choose api_version: "v2" for new integrations. To change it later, create a new endpoint.
  4. Set connect: true only if you need connected accounts' events.

An API request body looks like this:

{
  "name": "Production payment events",
  "url": "https://example.com/webhooks/paypercut",
  "enabled_events": ["payment.succeeded", "payment.failed"],
  "api_version": "v2",
  "connect": false
}

Get Your Signing Secret

Each endpoint has its own secret, shown in the Dashboard or returned by the Webhooks API. Put it in WEBHOOK_SECRET and use it as-is, without hex or base64 decoding. Paypercut recommends rotating it at least every quarter.

HTTP Method

Paypercut's docs don't name the HTTP method used for deliveries. Hookdeck's Paypercut source pre-selects POST without managing the method, so allow any other method the sender uses on the source. The linked skill examples, and the handler below, accept every method with app.all.

Test a delivery

Start a local receiver and forward requests with the Hookdeck CLI:

npx hookdeck-cli listen 3000 paypercut --path /webhooks/paypercut

Create a test endpoint with the CLI's URL and a couple of enabled_events, then make a test payment. Note the method, type and data shape of the first delivery.

Securing Paypercut webhooks

Split Paypercut-Signature on commas into t and v1. Build the message from the t text, a dot and the raw body, compute HMAC-SHA256 with the endpoint secret, and compare it with v1 in constant time. Paypercut's format line prints t=,v1=<hex_signature> with the timestamp missing, but its example (t=1768991448,v1=...) shows the real shape. See the webhooks guide.

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['paypercut-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const parts = signature.split(',').map((part) => part.trim());
  const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
  if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
  const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
  const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

The handler accepts any method, deduplicates on the event ID, and only returns 2xx once the event has been handled, as Paypercut asks.

const express = require('express');

function createPaypercutApp({ alreadyHandled, markHandled, handlers }) {
  const app = express();
  app.all('/webhooks/paypercut', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
    if (!req.body.length) return res.sendStatus(200);
    const eventId = req.headers['paypercut-event-id'];
    if (!eventId) return res.sendStatus(400);
    let parsed;
    try {
      parsed = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
    const { type, account, data } = parsed;
    if (typeof type !== 'string') return res.sendStatus(400);
    try {
      if (await alreadyHandled(eventId)) return res.sendStatus(200);
      const handler = handlers[type];
      if (handler) await handler(data, account);
      else console.log('Unhandled Paypercut event', type);
      await markHandled(eventId);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

Paypercut's docs recommend rejecting signatures more than 300 seconds old. The verifier above doesn't, so that retries and replays through Hookdeck (which keep the original header) still verify; if you receive directly from Paypercut and never replay, you can add the check on t.

Paypercut also suggests deduplicating on Paypercut-Delivery-Id, but that header identifies a delivery attempt. Paypercut-Event-Id stays the same across retries, so it's the better key.

Hookdeck's Paypercut source type parses t and v1 and checks the HMAC of {t}.{body} with your endpoint secret. It returns 200 to Paypercut in every case; a failure is recorded as failed verification and that request isn't forwarded. Hookdeck doesn't apply the 300-second window.

Make Paypercut webhooks production-ready. Hookdeck Event Gateway verifies each Paypercut event, separates direct and connected-account traffic, and keeps every payment and payout event replayable.

Paypercut webhook limitations and pain points

Undocumented retry schedule

The Problem: You don't know how long Paypercut keeps retrying a failed event.

Why It Happens: The docs say a 5xx is retried but give no attempts, spacing or timeout.

Workarounds:

  • Keep processing quick and idempotent, so retries are harmless.
  • Reconcile payments and payouts through the API after any outage.

How Hookdeck Can Help: Hookdeck takes the event on the first attempt and retries your service on a schedule you define.

"Process before acknowledging" guidance

The Problem: Slow handlers risk timeouts, while fast acknowledgements contradict Paypercut's advice.

Why It Happens: Paypercut asks for 2xx only after successful processing, yet states no timeout.

Workarounds:

  • Treat storing the event durably as "processed", and do slower work from a queue.

How Hookdeck Can Help: With Hookdeck in front, Hookdeck holds the event and your service can take the time it needs.

No published event body

The Problem: Parsers have to be written without a reference payload.

Why It Happens: Paypercut documents headers and event names, but its only body-shaped example is a validation snippet.

Workarounds:

  • Collect deliveries for each event in test mode and save them as fixtures.

How Hookdeck Can Help: Hookdeck stores the full body and headers of every delivery, so real examples are available from day one.

Fixed API version

The Problem: Upgrading from v1 to v2 payloads can't be done in place.

Why It Happens: api_version is set when the endpoint is created and can't be changed.

Workarounds:

  • Create a new v2 endpoint alongside the old one, migrate your handlers, then delete the v1 endpoint.

How Hookdeck Can Help: Two Hookdeck sources, one per endpoint, can run side by side during the migration with separate secrets.

Best practices

Keep t as text

Use the timestamp exactly as received. t=0001768991448 signs the string 0001768991448, not 1768991448.

Rotate secrets

Paypercut recommends rotating the endpoint secret at least quarterly. Keep it in a secret store so a rotation is one change.

Separate platform and connected-account events

If you use connect, check account on every event so actions are applied to the right merchant.

Make retries safe

Key on Paypercut-Event-Id, as our idempotency guide recommends, and move slow work out of the request path as described in asynchronous processing.

Conclusion

Paypercut follows a well-known model: exact event subscriptions, a fixed payload version, a Connect flag and a timestamped HMAC. The gaps are in the documentation rather than the design: no example bodies, no retry schedule, no stated HTTP method, and a dedup header that's per attempt rather than per event.

Hookdeck Event Gateway fills those gaps with stored deliveries, controlled retries and replay.

Get started with Hookdeck for free and handle Paypercut webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.