Karibu ID with ServiceNow — an integration recipe

A guide, not code, built only from Karibu ID's published contract (contracts/openapi.json, v0.57.0): the reader API, the reader webhooks and the exports (FA v5.7 §36.7). It describes one way a reader organisation can bring what Karibu ID holds into a ServiceNow vendor or third-party risk workflow. Karibu ID has no partnership with ServiceNow; ServiceNow is a trademark of its owner. Karibu ID reports findings, never verdicts: nothing here grades or predicts a company, and the decision on a supplier stays the reader's own.

What you need

• A reader organisation in Karibu ID with exports on, and a reader admin.
• In ServiceNow, a scripted REST endpoint (or an integration flow) that can receive an HTTPS POST, and a credential store for the webhook signing secret and a Karibu ID access token.

1. Receive the events

1. Read the catalogue: GET /v1/reader/webhooks/catalogue lists every event your endpoints can receive (share_granted, share_revoked, report_superseded, finding_new, the ledger_* events, reader_tier_changed, reader_decision_due, reader_invitation_status, questionnaire_answered and the others), each with a sample body.
2. Add the endpoint: POST /v1/reader/webhooks with your ServiceNow URL (https only). The answer holds the signing secret once; keep it in ServiceNow's credential store.
3. On each POST, verify KaribuID-Signature before anything else: split it into t and v1, refuse a t more than 300 seconds from your clock, compute HMAC-SHA256 with the decoded secret over t, a full stop and the raw body, and compare it with v1 in constant time. Answer 2xx quickly; Karibu ID retries a failed delivery with exponential backoff for 24 hours.
4. The body holds ids only (event_type, alert_id, ids, severity, occurred_at): no names, findings or personal data. Use the ids to fetch the detail, signed in.

2. Map events to work

3. Pull the detail

• The company's record, shared in full: GET /v1/reader/exports/records/{ke} (a signed JSON file that verifies at /v1/public/reports/{ks}/verify).
• The portfolio and its expiries: GET /v1/reader/exports/portfolio?format=csv and GET /v1/reader/exports/expiries?format=csv, for a scheduled import; follow X-Karibu-Next-Cursor for the next page.
• Decisions and audit packs: GET /v1/reader/exports/decisions and GET /v1/reader/exports/audit-packs/{ke}/{pack_id}.

4. Keep it within the rules

• Read only what a company shares with you; when a share ends, the routes answer 404 and the data stops: delete or mark what you copied.
• Never copy a person's details beyond what you need for the review; the webhook bodies carry none by design.
• Every export is in your access log and, for a company's record, in the company's too.