Subscribing to Webhooks

A webhook subscription is the pairing of one endpoint URL with a list of events. You can create and manage subscriptions from the Preczn dashboard or over the API — both act on the same subscriptions, so anything you create one way is visible and editable the other way.

What a subscription consists of

Field	Required	Description
Endpoint URL	Yes	The HTTPS URL we `POST` to. Must be a valid, publicly reachable URL.
Events	Yes	The events this subscription should receive. At least one. See the event catalog.
Active	Yes	Whether the subscription is currently delivering. New subscriptions are normally created active.
Description	No	A label for your own reference. Shown in the dashboard list.
Custom header key / value	No	One extra HTTP header sent with every notification. Use it to satisfy your own endpoint's authentication.

Two values are generated by Preczn and cannot be set by you:

Subscription ID — prefixed wh_ in Live mode and wh_test_ in Test mode.
Signing secret — used to sign every notification from this subscription. See Receiving and Verifying Webhooks.

📘
One subscription, one mode
A subscription is permanently scoped to the mode it was created in and will only ever receive events from that mode. To receive the same events in both Test and Live, create one subscription in each.

Subscribing from the dashboard

Open Settings → Webhooks. The Webhooks page lists your existing subscriptions with their ID, URL, description, subscribed events, and status.
Choose to add a new endpoint.
Enter the Endpoint URL, and optionally a Description.
Under Authorization, optionally add a custom header key and value. This is passed through verbatim on every notification, so it can carry an API key or an Authorization value that your endpoint already expects. (See MDN's HTTP headers reference for background.)
Under Events, select the events to subscribe to. They are grouped by domain — Transactions, Merchant, Loans, and Forms — with a count showing how many in each group you have selected.
Save the endpoint.

The subscription begins delivering immediately. From the list you can edit it, toggle it active or inactive, delete it, reveal its Signing Secret, and open its delivery history.

📘
Selecting events later
Editing the events on an existing subscription takes effect for subsequent events only. It does not backfill notifications for events that already happened.

Subscribing over the API

Webhook subscriptions are managed through the Merchant API using a private API key. The key determines both the platform and the mode of the subscriptions you can see and create — a Test-mode key creates and reads Test-mode subscriptions only.

Operation	Endpoint
Create a subscription	`POST /v1/webhooks`
Retrieve one subscription	`GET /v1/webhooks/{webhookId}`
List subscriptions	`GET /v1/webhooks`
Update a subscription	`PATCH /v1/webhooks/{webhookId}`
Delete a subscription	`DELETE /v1/webhooks/{webhookId}`

See API Keys for how to obtain and authenticate with a private key.

Creating a subscription

{
  "endpointUrl": "https://api.example.com/hooks/preczn",
  "active": true,
  "description": "Production transaction and boarding listener",
  "httpHeaderKey": "X-Api-Key",
  "httpHeaderValue": "your-endpoint-api-key",
  "events": [
    "transaction.approved",
    "transaction.declined",
    "merchant.updated",
    "form.completed",
    "form.expired"
  ]
}

The response contains the created subscription, including the generated id and signingSecret.

❗️
Save the signing secret from this response
The create response is the only place the API returns the signing secret. Later GET responses do not expose it. If you lose it, you can still reveal it in the dashboard under Settings → Webhooks, or create a replacement subscription.

Listing subscriptions

GET /v1/webhooks returns your subscriptions for the key's platform and mode:

{
  "webhooks": [],
  "lastKey": null
}

When more results remain, lastKey is populated. Pass it back as the lastKey query parameter to fetch the next page. A null lastKey means you have reached the end.

Updating a subscription

PATCH /v1/webhooks/{webhookId} accepts the same body as create.

⚠️
Update replaces, it does not merge
endpointUrl, active, and events are all required on a PATCH. Send the complete desired state of the subscription, not just the fields you want to change. In particular, omitting events fails validation rather than leaving the existing selection intact — so to add one event, send the full list including the new one.

To disable a subscription without deleting it, PATCH it with "active": false. It stops delivering and retains its ID, signing secret, and delivery history.

Deleting a subscription

DELETE /v1/webhooks/{webhookId} returns 204 No Content. Deletion is permanent — the subscription and its signing secret cannot be recovered. Disable instead if you may want it back.

Errors

Status	Message	Cause
`400`	Validation error	An event value is not in the catalog, `endpointUrl` is not a valid URL, or a required field is missing.
`401`	`Unauthorized`	The API key's mode does not match the subscription's mode — for example a Live key requesting a `wh_test_` subscription.
`403`	`Resource Forbidden`	The subscription belongs to a different platform.
`404`	`Webhook not found`	No subscription exists with that ID.

FAQ

Should I use the dashboard or the API?

Use whichever fits your workflow — they manage the same subscriptions. The API is the better choice when subscriptions are part of your environment provisioning, so a new environment can configure its own endpoint without anyone logging in. The dashboard is the only place to browse delivery history, and the only place to resend a past transaction notification.

Can two subscriptions point at the same URL?

Yes. Each is independent, with its own signing secret, event list, and failure counter, and each delivers separately — so the same URL would receive one notification per matching subscription. This is a practical way to rotate a signing secret with no downtime: add a second subscription to the same URL, accept both secrets in your handler, then remove the first.

What happens to events that occur while a subscription is inactive?

They are not delivered and are not queued for later. An inactive subscription misses events for the entire period it is inactive, with no backfill when you re-enable it. If a subscription was disabled automatically after repeated failures, reconcile the gap against the API before relying on the resumed stream — see Delivery, Retries, and Failures.

Can I use HTTP instead of HTTPS?

Use HTTPS. Notifications can contain merchant and contact details, and sending them unencrypted would expose that data in transit. HTTPS is also what makes signature verification meaningful — over plain HTTP an attacker who can read the traffic can also alter it.

Can I set more than one custom header?

No — a subscription supports a single header key and value. If your endpoint needs several, put the value in one header and derive the rest server-side, or place the credential in the URL path so the endpoint itself is unguessable. Signature verification remains the mechanism for confirming a request came from Preczn; the custom header is for your own endpoint's authentication.

Does changing the endpoint URL reset anything?

The signing secret and subscription ID are unchanged, so your existing verification code keeps working. The consecutive-failure counter is not cleared by the edit itself — it resets on the next successful delivery. If the subscription was already auto-disabled, updating the URL does not re-enable it; set it active again explicitly.