generic webhook adapter
The webhook-adapter lets you connect any payment system or internal service that can send JSON event data to a URL. You configure a field mapping in the Ledgerise UI that tells the adapter how to find each canonical field in your payload — no code required.
when to use this adapter
Use the generic webhook adapter when:
Your source system can POST transaction events to a URL on each transaction.
Your payload is JSON (single record or array of records).
The field mapping from your payload to the canonical schema is straightforward — no conditional logic, computed fields, or proprietary encoding.
If your source system requires a custom authentication handshake, has a non-JSON format, or needs conditional type mapping logic, consider building a custom adapter instead.
how it works
Ledgerise exposes a unique webhook URL for your deployment.
You configure your source system to POST transaction events to that URL.
The adapter receives the payload, runs it through your field mapping, validates the result, and normalizes it into the canonical transaction schema.
The transaction record appears in the Transactions page within seconds.
configuration
Go to Settings → Adapters → webhook-adapter → Configure.
Endpoint path
Yes
The URL path Ledgerise exposes for this webhook. Copy this and enter it in your source system.
Signing secret
No
A shared secret used to verify the payload's signature. If your source system supports HMAC signature verification, enter the secret here. Ledgerise will reject payloads that fail signature verification.
Field mapping
Yes
Maps canonical schema fields to paths in your JSON payload (dot notation supported).
field mapping
The field mapping tells the adapter where to find each canonical field in your payload. Use dot notation for nested fields.
Example: if your payload looks like this:
Your mapping would be:
source_id
txn.id
amount
txn.amount_ngn
status
txn.status
type
txn.type
occurred_at
txn.timestamp
principal.reference
customer.phone
supported payload formats
The adapter accepts JSON payloads containing either:
A single record — the top-level object is the transaction.
An array of records — the top-level object is an array; each element is processed as a separate transaction.
XML, form-encoded, and other non-JSON formats are not supported by the generic adapter. Build a custom adapter for those.
testing your webhook
Once configured, send a test payload from your source system to the webhook URL. The transaction should appear in the Transactions page within a few seconds. If it doesn't:
Check Settings → Adapters → webhook-adapter for a red healthcheck status or error notice.
Go to the Transactions page and look for a record with
posting_status: failed— the detail drawer will show the validation error from the adapter.Confirm your payload matches the expected structure and that your field mapping paths are correct.
limitations
JSON only. No XML, CSV, or proprietary binary formats.
No built-in support for pagination or bulk payloads beyond a top-level array.
No conditional field mapping — if a canonical field needs to be derived from multiple source fields or requires conditional logic, build a custom adapter.
Status mapping: the adapter attempts to map common status strings (
successful,failed,pending,reversed,disputed) to canonical values. If your source system uses non-standard status values, you may need a custom adapter.
Last updated
