Skip to main content

Integrator guide — one key, many clients

VAS and multi-bank integrators post once to their partner webhook URL and route events to client tenants on their roster.

Fan-out ingress​

POST /api/v1/partner/webhooks/<integrator_partner_id>/
X-Partner-Signature: <hmac_sha256_hex(raw_body, integrator_webhook_secret)>
X-Client-Partner-Id: <client_partner_id>
Content-Type: application/json

Alternatively include "client_partner_id": "<client_partner_id>" in the JSON body.

Signing​

  1. Build the JSON body (UTF-8).
  2. HMAC-SHA256 the exact raw bytes with the integrator webhook secret.
  3. Send the hex digest as X-Partner-Signature (legacy alias: x-tumitrust-signature).
  4. Do not use X-TumiTrust-Webhook-Secret — that header is not accepted.

Rules

  1. Authenticate as the integrator (signature / secrets on the integrator profile).
  2. Integrator entitlements must set integrator.client_webhook_routing to per_client_partner_id.
  3. client_partner_id must appear on integrator.client_partner_ids.
  4. The resulting TrustEvent is stored under the client partner_id (Pulse stays tenant-correct).

Cross-roster clients receive 403 with client_not_on_integrator_roster.

Rail dimensions​

Payload fields (optional):

FieldMeaningExamples
channelDelivery railsms, ussd, agent, app, api, other
programProduct / collection lineagency, fisp, cdf, wirepick_pay, telehealth, …

These are stored on TrustEvent.rail_channel and TrustEvent.program_key (indexed). They are not the same as ingest_source (webhook / csv / api / connector).

Embeds for client desks​

Client LOSes iframe the trust card and mint screening tokens with the client partner id:

SurfacePath
Trust card/embed/v1/<client_partner_id>/<context_id>/<entity_id>/
Screening tokenPOST /api/v1/partner/embed/screening/<client_partner_id>/token/
Screening frame/embed/v1/screening/<client_partner_id>/?embed_token=…

Use canonical context ids (lending, agricultural, …). Integrator Embed Studio attaches clients and preview subjects; production embeds still point at the client id.

Add client (console)​

Integrators with Embed Studio access can provision a client vertical template and attach_client from the studio — no second provision engine.