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 and receiving guide:
- Requests are
POSTwith a JSON body,Content-Type: application/jsonandUser-Agent: Preczn/<version>. - An optional custom header configured on the subscription is sent verbatim, for your endpoint's own authentication.
- A
2xxwithin 5 seconds is success and resets the subscription's failure counter. 5xxresponses, connection errors and timeouts are retried up to 3 times with exponential backoff. A4xxis 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
eventslist 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:
{
"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
- Create a subscription in the Preczn dashboard or with the API, choosing the mode, the HTTPS endpoint and the events.
- 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. - 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:
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
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.
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 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, never4xx, 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
idfor retries, and apply changes keyed on the record insidedata, such asdata.idfor a transaction ordata.formIdfor a form. - Compare timestamps like
modifiedOnand 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
datatimestamps 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 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 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 keeps Preczn subscriptions healthy and gives you longer retries and replay.
Get started with Hookdeck for free and handle Preczn webhooks reliably in minutes.