# Guide to Preczn Webhooks: Features and Best Practices

Preczn sits between software platforms and payment processors, handling merchant boarding, transaction routing and merchant loans. Its webhooks tell your platform when a transaction is approved or declined, a merchant record changes, a loan is recorded, or a merchant moves through a boarding form, so you don't have to poll the API to find out.

You'll find here how Preczn subscriptions are scoped, the 14 events, the `v1=` signature format and how it supports secret rotation, and the difference between a retry and a resend.

## What are Preczn webhooks?

A Preczn webhook subscription has an HTTPS endpoint, a list of events and a signing secret, and belongs to one platform and one mode. A Test-mode subscription only receives Test events and a Live one only Live events, so to get both you create two subscriptions. If several of your subscriptions match an event, each gets its own delivery.

Subscriptions can be managed in the dashboard or through the API, and both see the same records. The dashboard also shows delivery history and can resend past transaction notifications.

## Preczn webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-preczn-signature` |
| Body | JSON |
| Event routing | Body field `eventType` |

From Preczn's [webhooks overview](https://docs.preczn.com/docs/webhooks) and [receiving guide](https://docs.preczn.com/docs/receiving-and-verifying-webhooks):

* Requests are `POST` with a JSON body, `Content-Type: application/json` and `User-Agent: Preczn/<version>`.
* An optional custom header configured on the subscription is sent verbatim, for your endpoint's own authentication.
* A `2xx` within 5 seconds is success and resets the subscription's failure counter.
* `5xx` responses, connection errors and timeouts are retried up to 3 times with exponential backoff. A `4xx` is never retried.
* 25 consecutive failed notifications disable the subscription and email its creator.
* Each attempt is kept in delivery history for 15 days, with the full body and your response.
* The `events` list is required, and new event types are never added to an existing subscription automatically.

## Events and payloads

Route on the top-level `eventType`. Preczn currently documents 14 events. The first eight:

| Event routing | Body field `eventType` |

The remaining six are `loan.updated` (an existing loan account's details or status change) and the boarding form events: `form.created`, `form.started` (a merchant completes a section for the first time), `form.updated`, `form.completed` and `form.expired` (an unfinished form passes its expiration time).

Every body has the same four fields, and only `data` changes:

```json
{
  "id": "what_6k022ss0jj8vp9g85xv1z357m7",
  "webhookId": "wh_5jg1dx62za981aqkanv3cd99zh",
  "eventType": "transaction.approved",
  "data": {}
}

```

`id` is prefixed `what_` in Live mode and `what_test_` in Test mode. The `data` shape for each event is on Preczn's separate Transaction, Merchant, Loan and Boarding Form payload pages. Preczn says transaction data includes only the card brand, BIN and last four digits, and form data only identifiers, statuses and timestamps, never the form's contents.

## Setting up Preczn webhooks

1. Create a subscription in the Preczn dashboard or with the API, choosing the mode, the HTTPS endpoint and the events.
2. Copy the signing secret. The API returns it only in the create response, while the dashboard can reveal it any time under **Settings > Webhooks** with the view icon next to the subscription. Store it as `PRECZN_WEBHOOK_SECRET`, with a separate value per subscription.
3. Generate some Test-mode activity and check the subscription's delivery history.

To route through Hookdeck, create a Preczn source with the subscription's signing secret and use the source URL as the endpoint. Since Test and Live subscriptions have different secrets, give each its own Hookdeck source. To test locally:

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

```

## Securing Preczn webhooks

`X-Preczn-Signature` holds one or more comma-separated values of the form `v1=<hex>`. Each is the lowercase hex HMAC-SHA256 of the raw request body, keyed with the signing secret as UTF-8. During a secret rotation Preczn signs with both secrets and sends both signatures, and the request is genuine if any one matches.

Preczn's FAQ names the usual causes of mismatches: hashing a re-serialised body, using the secret from a different subscription (check `webhookId`), comparing base64 instead of hex, and forgetting to strip `v1=`.

### Node.js verification

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

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-preczn-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = signature.split(',').map((part) => part.trim())
    .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 stores each notification by `id` and acknowledges inside the 5-second window. It returns `200` for event types it doesn't use, as Preczn recommends, since errors count towards the 25-failure limit.

```javascript
const express = require('express');

const app = express();

app.post('/webhooks/preczn', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.PRECZN_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  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 { id, webhookId, eventType, data } = parsed;

  try {
    await inbox.insertIfNew(id, { webhookId, eventType, data });
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

```

Storage errors return `503` so Preczn retries. A `401` on a bad signature is a `4xx` and won't be retried, which is what you want for a forged request.

Hookdeck's Preczn source checks every `v1=` value in the header, so rotation works without changes. It answers `200` and records failures as failed verification rather than rejecting them. Preczn signs nothing time-bound, and Hookdeck doesn't add a time window.

> **Make Preczn webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) replies to Preczn within its 5-second timeout and keeps notifications beyond Preczn's 15-day history, with retries and replays to your platform.

## Preczn webhook limitations and pain points

### Only three retries, then the event is gone

**The Problem:** A short outage can lose notifications for good.

**Why It Happens:** Preczn retries a failed notification up to 3 times with exponential backoff, then increments the failure counter and moves on. Dashboard resends are available for transaction deliveries only.

**Workarounds:**

* After any downtime, reconcile merchants, loans and forms against the Preczn API, which Preczn itself recommends as a backstop.
* Return `5xx`, never `4xx`, when you want a retry.

**How Hookdeck Can Help:** Hookdeck accepts the notification on the first attempt and retries your service on a schedule you configure, for as long as you need.

### 25 failures disable the subscription

**The Problem:** A sustained outage or a bad deploy stops all notifications.

**Why It Happens:** After 25 consecutive failed notifications, Preczn disables the subscription and emails its creator.

**Workarounds:**

* Make sure the mailbox of whoever created the subscription is monitored.
* Follow Preczn's recovery steps, then reconcile from the API for the gap.

**How Hookdeck Can Help:** Hookdeck always answers Preczn successfully, so the failure counter stays at zero while your service recovers.

### Resends carry a new id

**The Problem:** Deduplicating on `id` alone lets a resent event through twice.

**Why It Happens:** A retry repeats the identical body with the same `id`, but a dashboard resend reuses the `eventType` and `data` under a new `id`.

**Workarounds:**

* Deduplicate on `id` for retries, and apply changes keyed on the record inside `data`, such as `data.id` for a transaction or `data.formId` for a form.
* Compare timestamps like `modifiedOn` and ignore older state.

**How Hookdeck Can Help:** Hookdeck deduplication can key on fields inside `data` as well as `id`, which catches both cases within a time window.

### Notifications arrive out of order

**The Problem:** A `merchant.updated` can arrive before the `merchant.created` it follows, or an older state can arrive after a newer one.

**Why It Happens:** Preczn doesn't guarantee ordering, even for the same record.

**Workarounds:**

* Store the latest state per record and compare `data` timestamps before overwriting.
* Fetch the record from the API when a notification refers to something you haven't stored.

**How Hookdeck Can Help:** Hookdeck's retries let your service return an error for a record it isn't ready for and receive the notification again later.

## Best practices

### Keep Test and Live apart

Subscriptions, secrets and ID prefixes differ by mode. Check for `what_test_` or `wh_test_` and refuse Test notifications in your production environment.

### Use the custom header only as an extra check

A custom authorization header helps your gateway accept the request, but Preczn is clear that only the signature proves origin and integrity.

### Acknowledge, then process

Five seconds is the hard limit. Save the notification and do the processor or accounting work afterwards. This [async processing guide](/webhooks/guides/why-implement-asynchronous-processing-webhooks) explains why.

### Converge on the same state

Preczn's own test is that handling a notification twice should leave you where handling it once would. The [idempotency guide](/webhooks/guides/implement-webhook-idempotency) covers the techniques.

## Conclusion

Preczn notifies software platforms about transactions, merchants, loans and boarding forms, scoped by platform and mode and signed with one or more `v1=` HMAC-SHA256 values. Its delivery rules are explicit: 5 seconds to respond, three retries, `4xx` never retried, and a subscription disabled after 25 failures. Retries and resends need different deduplication.

[Hookdeck Event Gateway](https://hookdeck.com) keeps Preczn subscriptions healthy and gives you longer retries and replay.

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