# 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).

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/paypercut-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/paypercut-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/paypercut-webhooks/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](https://hookdeck.com/docs/sources#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_session.completed` | A Checkout Session has been completed |
| `payment.succeeded` | A payment has succeeded |
| `payment.failed` | A payment has failed |
| `payment_intent.authorized` | 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_session.verified` | 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/paypercut-webhooks/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

```bash
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):

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

```

Use the printed URL as the endpoint URL in Paypercut.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/paypercut-webhooks/references/overview.md) - What Paypercut webhooks are, full event list, headers
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/paypercut-webhooks/references/setup.md) - Create an endpoint and get the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/paypercut-webhooks/references/verification.md) - Signature details, gotchas, debugging
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/paypercut-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests