Webhooks

BigLedger can POST to a URL of yours when something changes in a tenant, so your system does not have to poll for it.

This page documents what that mechanism does and — at least as important — what it does not do. Read the guarantees section before you design around it.

What it is

You register a subscription: a URL, a topic, and optionally one HTTP header for the receiver to authenticate with. When a matching change happens in that tenant, BigLedger POSTs a JSON body to your URL. Every attempt is written to a delivery log.

Topics are strings such as CUSTOMER_CREATED, INTERNAL_SALES_INVOICE_CREATED or INVENTORY_UPDATED. A subscription points at one topic. For several topics, register several subscriptions.

What it does not do

Four absences, all of which change how you should build.

Setting one up

Step 1 — make sure the topic exists

A subscription points at a topic record, not at a topic string, so the record has to exist first.

curl -s "https://api-etl.akaun.com/core2/tnt/dm/webhook-topic/query?limit=200" \
  -H "AccessId: $BLG_ACCESS_ID" -H "AccessKey: $BLG_ACCESS_KEY" -H "tenantCode: $BLG_TENANT_CODE"

If the list is empty, the tenant has never been seeded. Seeding is one call and it is idempotent:

curl -s -X POST "https://api-etl.akaun.com/core2/tnt/dm/webhook-topic/populate-default" \
  -H "AccessId: $BLG_ACCESS_ID" -H "AccessKey: $BLG_ACCESS_KEY" -H "tenantCode: $BLG_TENANT_CODE"

That inserts the platform’s built-in list of 54 topics. Take the guid of the one you want from the query above.

Step 2 — create the subscription

curl -s -X POST "https://api-etl.akaun.com/core2/tnt/dm/webhook-subscription" \
  -H "AccessId: $BLG_ACCESS_ID" -H "AccessKey: $BLG_ACCESS_KEY" \
  -H "tenantCode: $BLG_TENANT_CODE" -H "Content-Type: application/json" \
  -d '{
        "bl_webhook_subscription_hdr": {
          "topic_hdr_guid": "<guid of the topic record>",
          "url": "https://hooks.gadgetsphere.example/blg/sales-invoice-created",
          "auth_header_name": "X-GadgetSphere-Token",
          "auth_header_value": "<a long random string>",
          "status": "ACTIVE"
        }
      }'

Managing subscriptions:

These need the tenant permissions API_TNT_DM_WEBHOOK_SUBSCRIPTION_CREATE, _UPDATE, _DELETE and _READ, or tenant owner or administrator rank. Step 1 additionally needs API_TNT_DM_WEBHOOK_TOPIC_READ to list topics and API_TNT_DM_WEBHOOK_TOPIC_CREATE to seed or create them. Ask for all of them when you ask for the integration user — a key that can read records cannot manage subscriptions unless it was granted these too.

What success looks like

Thirty seconds, and worth spending before you write any receiving code.

1. Point the subscription at a request-capture service (https://webhook.site/… or your own nc -l 8080) instead of your real endpoint.
2. Make the change the topic names — for CUSTOMER_CREATED, create one customer in the tenant.
3. Within a second or two you should see one POST, Content-Type: application/json, carrying the header name and value you set, and a body whose top-level key is a table name such as bl_fi_mst_entity_hdr.

If nothing arrives, work backwards in this order: the topic record exists and its topic_code matches the platform’s string exactly; the subscription’s status is ACTIVE; the url has no typo (it is not validated, so a wrong one fails silently and forever); the topic is one the platform actually emits, not merely one populate-default seeded. If the POST arrives but has no authentication header, the subscription was created in the Web Hook screen rather than through the API — delete it and create it again with both header halves.

What arrives at your endpoint

POST /blg/sales-invoice-created HTTP/1.1
Host: hooks.gadgetsphere.example
Content-Type: application/json
X-GadgetSphere-Token: <your auth_header_value>

{ "bl_fi_generic_doc_hdr": { … }, "bl_fi_generic_doc_line": [ … ] }

Always POST. Always application/json. The method is not configurable.

The body is the record itself, in the same container shape the Data API returns — and nothing else.

Your endpoint should return quickly — acknowledge, queue, and process asynchronously. BigLedger allows 60 seconds to establish the connection and then waits indefinitely for your response, and delivery for the whole platform runs on a small shared pool. An endpoint that accepts a connection and then hangs is worse than one that fails fast.

Topics

POST /core2/tnt/dm/webhook-topic/populate-default seeds 54 topics. The ones most integrations use:

Some seeded topics never fire, because the code path they name does not emit them — the supplier sales-order and supplier sales-return topics are the clearest example. And document topics follow the pattern <SERVER_DOC_TYPE>_CREATED / _UPDATED / _DELETED, so document types beyond the seeded handful do emit events; their topic records just have to be created by hand.

Before you build on a topic, test it. Subscribe, make the change in the tenant, and confirm your endpoint is called. A topic that is registered but never fires looks identical to a quiet system.

How to build on this

The pattern that works:

1. Subscribe to the topics you care about, one URL each.
2. Treat every delivery as “something may have changed” — take the GUID from the body, and re-read the record through …/etl-ep/{guid} before acting.
3. Reconcile on a schedule with an updated_date_from pull. This catches everything the webhook dropped, and it is the part you must not skip.
4. Log every delivery on your side, with the raw body. The platform’s own log is not readable.
5. Return 200 fast. Queue the work.

The webhook makes your integration responsive. The reconciliation pull makes it correct. You need both.

Related documentation