Integrations overview

The Connect layer lets you pipe fine-grained platform events into Zapier, n8n, or your own systems, and drive the platform (create verification sessions, run AML checks, tag sessions) from those tools.

Where the classic tenant webhook (see Webhooks) is one URL that receives terminal decisions, Connect gives you many endpoints, each with its own subscription filter and signing secret:

Pick your events

25+ event types across the whole lifecycle — per-module results, AML hits, review-case movement, applicant progress, credit alerts — not just the final decision. Wildcards like session.* or ["*"] work too.

Scope by workflow & module

Restrict an endpoint to specific workflow_ids, and restrict module.completed / aml.hit to specific modules (AML_SCREENING, LIVENESS, …).

Same delivery guarantees

Every endpoint rides the existing pipeline: HMAC-signed, SSRF-guarded, 15s timeout, retried on the 1m→5m→30m→1h→24h backoff, fully visible in the console delivery log.

Endpoints created by Zapier or n8n appear automatically on the console Connect page (Console → Developers → Connect) with a source badge, so an operator can see, test-fire, pause, or debug a Zap's subscription without leaving the console.

Warning

Connect is a platform-managed, opt-in feature — it's off until your platform administrator enables it for your account. While it's off, the whole /v3/automation/ surface returns 403 (so Zapier/n8n can't even establish a connection), no Connect events are delivered — including to endpoints created earlier — and the console Connect page shows a "not enabled" notice. The classic single tenant webhook keeps working regardless.

The envelope

Every Connect delivery POSTs one event in a stable envelope:

{
  "payload_version": 1,
  "event": "session.approved",
  "id": "11111111-2222-3333-4444-555555555555",
  "created_at": "2026-07-16T10:04:12Z",
  "data": {
    "session": {
      "id": "6a1f6f7e-…",
      "status": "approved",
      "workflow": { "id": "1f2e3d4c-…", "name": "Standard KYC" },
      "vendor_data": "user-42",
      "risk_score": 12,
      "risk_level": "low",
      "url": "https://acme.verify.example.com/verify/tok_…",
      "created_at": "2026-07-16T10:00:00Z",
      "completed_at": "2026-07-16T10:04:12Z"
    }
  }
}

event — the event key; route on this.
id — unique per event; dedupe on this (delivery is at-least-once).
data — event-specific: session, plus module, case, aml, detail, or credits depending on the event. See the event catalog for a sample of every event.

Payloads are sanitized before shipping — evidence images, base64 blobs, internal media paths and secrets are stripped, long strings truncated.

Note

Signing uses the same scheme as the classic webhook — X-Webhook-Signature: t=<unix>,v1=<hex> where v1 is HMAC-SHA256("<t>.<raw_body>", secret) — but with the endpoint's own secret, returned once when the endpoint is created. Verification code from verifying signatures works unchanged.

Managing endpoints

Two equivalent surfaces manage the same endpoints:

Console → Developers → Connect (requires the manage integrations permission): create endpoints with a grouped event picker, workflow and module filters, reveal-once secrets with rotation, a per-endpoint delivery log, and a test-fire button that sends the event's sample payload through the real signed pipeline.

Authenticated with your tenant API key (x-api-key or Authorization: Bearer), throttled per tenant:

Method & path	Purpose
`GET /v3/automation/me/`	Auth test → tenant name
`GET /v3/automation/events/`	Event catalog + module keys (drives dropdowns)
`GET /v3/automation/subscriptions/`	List subscriptions
`POST /v3/automation/subscriptions/`	Subscribe — returns the signing `secret` once
`GET /v3/automation/subscriptions/<id>/`	Inspect one
`PATCH /v3/automation/subscriptions/<id>/`	Update url / events / filters / active
`DELETE /v3/automation/subscriptions/<id>/`	Unsubscribe (idempotent)
`GET /v3/automation/samples/<event>/`	Recent real payloads for an event, else a static sample

Subscribe example:

curl -s -X POST https://acme.thirdfactor.ai/v3/automation/subscriptions/ \
  -H "x-api-key: $OBSIDIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/kyc",
    "events": ["session.approved", "session.declined", "aml.hit"],
    "workflow_ids": ["1f2e3d4c-5b6a-4978-8899-aabbccddeeff"],
    "description": "CRM sync"
  }'

{
  "ok": true,
  "id": "b7f3…",
  "secret": "whsec_…",        // shown once — store it now
  "events": ["session.approved", "session.declined", "aml.hit"],
  "workflow_ids": ["1f2e3d4c-…"],
  "source": "api",
  "active": true
}

This is the API the Zapier app and n8n node use under the hood (with source: "zapier" / "n8n"), so anything they can do, your own code can too.

Delivery semantics

Connect deliveries differ from the classic webhook in one way: the first attempt is dispatched asynchronously (a background worker), so the request that produced the event never waits on your sink. Everything else matches the classic pipeline — at-least-once delivery, the same backoff schedule, no redirects followed, HTTPS-only targets, and per-delivery visibility in the console.

Design your receiver exactly as the idempotent-handler guidance describes, deduping on the envelope's id.

Zapier

Install the Zapier app: triggers for approvals, declines, reviews, AML hits, per-module results — plus create-session and AML-check actions.

n8n

The community node: a trigger node with dynamic event dropdowns and signature verification, and an action node for sessions and tools.

Event catalog

Every subscribable event with a sample payload.