# Guide to Paypercut Webhooks: Features and Best Practices

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](https://dashboard.paypercut.io/developers/webhooks) 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

| Feature | Details |
| --- | --- |
| Configuration | Merchant Dashboard, or `POST /v1/webhooks` |
| Event selection | `enabled_events`, exact identifiers only |
| Payload version | `api_version` per endpoint, fixed at creation |
| Connected accounts | `connect: true`, with top-level `account` |
| Signature | hex HMAC-SHA256 |
| Signature header | `paypercut-signature` (`t=<unix>,v1=<hex>`) |
| Signed content | `<t>.<raw body>` |
| Key | The endpoint's own secret |
| Body | JSON |
| Event routing | Body field `type` |
| IDs | `Paypercut-Event-Id`, `Paypercut-Delivery-Id` |
| Retries | On `5xx`; schedule undocumented |
| HTTP method | Not documented |

## Events and payloads

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `checkout_session.completed` | A Checkout Session has been completed | Fulfil an order |
| `payment.succeeded` | A payment has succeeded | Mark an order as paid |
| `payment.failed` | A payment has failed | Notify the customer, retry |
| `payment_intent.authorized` | A Payment Intent has been authorized | Capture when ready |
| `payment_intent.captured` | A Payment Intent has been captured | Record captured funds |
| `payout.paid` | A payout has been paid | Reconcile settlements |
| `payout.failed` | A payout has failed | Alert finance |
| `account.updated` | An account has been updated | Refresh a connected account's status |
| `invoice.paid` | An invoice has been paid | Extend a subscription |
| `invoice.payment_failed` | Payment for an invoice has failed | Dunning |
| `identity.verification_session.verified` | An identity verification session has been verified | Unlock 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](https://dashboard.paypercut.io/developers/webhooks), 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:

```json
{
  "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](/docs/cli):

```bash
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](https://docs.paypercut.io/docs/introduction/start-developing/webhooks).

```javascript
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.

```javascript
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](/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](/webhooks/guides/implement-webhook-idempotency) recommends, and move slow work out of the request path as described in [asynchronous processing](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) fills those gaps with stored deliveries, controlled retries and replay.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Paypercut webhooks reliably in minutes.