Receiving and Verifying Webhooks

This page covers everything your endpoint needs to do: read the notification, prove it came from Preczn, and respond correctly.

The request we send

Every notification is an HTTP POST with a JSON body. The body has the same four top-level fields for every event type — only data changes shape.

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

For the shape of data per event, see Transaction, Merchant, Loan, and Boarding Form payloads.

Headers

How to respond

Make your handler idempotent

The same event can reach your endpoint more than once, and ordering is not guaranteed. Two mechanisms cause repeats, and they need different defenses:

• A retry — after a timeout your server actually processed, for example — re-sends the identical body, including the same top-level id. Deduplicate on id: record the id of every notification you process and ignore repeats.
• A resend, triggered from the dashboard, reuses the original eventType and data but is issued a new id. Deduplicating on id will not catch it.

So id alone is not sufficient. Make the effect of handling a notification idempotent as well:

• Key off the record, not the notification. Apply changes by the identifier inside data — data.id for a transaction, data.formId for a boarding form — so processing the same state twice converges instead of double-counting.
• Ignore stale state. Where data carries a timestamp such as modifiedOn, compare it to what you have stored and discard anything older rather than overwriting newer state.

The practical test: handling the same notification twice should leave your system in the same state as handling it once.

Verifying the signature

Every notification is signed with the subscription's signing secret, so you can confirm it genuinely came from Preczn and was not modified in transit. Verify before you act on the contents.

The signature travels in the X-Preczn-Signature header:

X-Preczn-Signature: v1=fd2118dc6da5fda8ae597a4ddfea31c691335b73613b15936a4ab49c632d3658

The current version is v1: an HMAC of the raw request body, using SHA-256, rendered as lowercase hexadecimal.

The header may contain more than one signature, comma-separated. This supports zero-downtime secret rotation and future algorithms. The request is authentic if at least one signature matches your computed value.

Steps

1. Extract the X-Preczn-Signature header.
2. Split on , if multiple signatures are present.
3. Strip the v1= prefix from each.
4. Compute the expected signature over the entire raw request body.
5. Compare each received signature against your computed one. If any match, trust the request. If none match, discard it.

Computing the expected signature

const crypto = require('crypto');

function generateWebhookSignature(signingSecret, requestBody) {
    const hmac = crypto.createHmac('sha256', signingSecret, { encoding: "utf-8" });
    const data = hmac.update(requestBody);
    return data.digest('hex');
}

import hmac
import hashlib

def generate_webhook_signature(signing_secret, request_body):
    signing_bytes = bytearray(signing_secret.encode(encoding='UTF-8'))
    request_bytes = bytearray(request_body.encode(encoding='UTF-8'))
    return hmac.new(
        signing_bytes,
        request_bytes,
        hashlib.sha256,
    ).hexdigest()

using System;
using System.Security.Cryptography;
using System.Text;

private static string GenerateWebhookSignature(string signingSecret, string requestBody)
{
  byte[] signingSecretBytes = Encoding.UTF8.GetBytes(signingSecret);
  byte[] requestBodyBytes = Encoding.UTF8.GetBytes(requestBody);
  HMACSHA256 hash = new HMACSHA256(signingSecretBytes);
  byte[] hashBytes = hash.ComputeHash(requestBodyBytes);
  return BitConverter.ToString(hashBytes).Replace("-","").ToLower();
}

Custom headers are not a substitute

If you configured a custom header on the subscription, it is sent verbatim with every notification and is useful for satisfying your endpoint's own authentication. It does not prove the request came from Preczn or that the body is unmodified — only the signature does that. Verify the signature regardless.

FAQ