Webhooks overview

Obsidian pushes a signed HTTP POST to your endpoint when something decisive happens: a verification session settles, an application changes decision, or a risk-list match forces a review. The webhook is the channel you build on — the result your browser or mobile SDK receives is a UX hint, nothing more.

Configure the endpoint URL and signing secret in Console → Developers → Webhooks. That screen also lists every delivery attempt with its response code, lets you resend a delivery, and has a test-send button.

Why a webhook and not just the redirect result

Use the client result to update the UI. Use the webhook — or a direct GET .../decision/ poll — to gate anything that matters: account creation, fund transfers, access grants.

Delivery lifecycle

Every delivery is a row in the tenant's WebhookDelivery log (visible in Console → Developers → Webhooks) that moves through three states:

                    enqueue_delivery()
                            │
                            ▼
                    ┌───────────────┐
    application/    │    PENDING    │   HTTP POST, 15s timeout
    session reaches │  attempt = 0  │   X-Webhook-Signature +
    a terminal state└───────┬───────┘   X-Webhook-Delivery headers
                            │
              immediate in-process attempt (attempt 1)
                            │
              ┌─────────────┴─────────────┐
              │                           │
         2xx response                non-2xx / timeout /
              │                       SSRF-blocked / DNS fail
              ▼                           ▼
      ┌───────────────┐           ┌────────────────────┐
      │   DELIVERED    │           │ retry scheduled at  │
      │ delivered_at   │           │  next_attempt_at    │
      │ set, done      │           │  (backoff schedule) │
      └───────────────┘           └──────────┬──────────┘
                                              │
                          Celery beat polls every 60s for
                          due rows → attempt_delivery() again
                                              │
                              ┌───────────────┴───────────────┐
                              │                                │
                         2xx response                  non-2xx again,
                              │                     attempt >= max attempts
                              ▼                                ▼
                      ┌───────────────┐             ┌────────────────────┐
                      │   DELIVERED    │             │       FAILED        │
                      └───────────────┘             │  (visible + resend-  │
                                                      │   able in console)  │
                                                      └────────────────────┘

The first attempt happens synchronously, in-process, at the moment the event is enqueued — so a healthy endpoint typically sees the delivery within the same request cycle that produced the decision. Only failures fall through to the polling retry path.

Retry and backoff behavior

Delivery is at-least-once. A failed attempt (any non-2xx status, a timeout, a DNS failure, or an SSRF-guard rejection) is retried on a fixed backoff schedule, doubling the previous gap roughly five-to-tenfold each step:

If attempt 6 also fails, the delivery is marked failed permanently — it will not be retried automatically again, but it stays visible in Console → Developers → Webhooks and you (or your tenant admin) can trigger a manual Resend, which creates a fresh delivery row with the same idempotency_key and makes one synchronous attempt immediately.

Consequences of this model, worth designing around:

• The same event can arrive more than once. A resend, a retry racing a slow-but-eventually-successful original attempt, or an operator-triggered resend of an already-delivered event can all put the same idempotency_key on your queue twice.
• Events can arrive out of order. A .review event's retry can be in-flight when the .approved event that supersedes it fires and succeeds on the first try. Don't assume monotonic arrival — compare created_at, or re-read the authoritative decision from the API when in doubt.
• An endpoint that is down for more than ~26 hours loses events for good (1 + 5 + 30 + 60 + 1440 minutes of backoff ≈ 26 hours of retrying). Anything that fails permanently is still visible and resendable in the console, but nothing pages you automatically — monitor delivery health from your side too (see Troubleshooting below).

Two envelope shapes

There are two families of events, and their payloads differ. Both are signed the same way and both add event_type and idempotency_key.

{
  "session_id": "6f0e2b7a-…",
  "status": "approved",
  "workflow_id": "9c1f…",
  "vendor_data": "your-user-reference-123",
  "decision": {
    "LIVENESS": {
      "feature": "LIVENESS", "status": "approved", "score": 91.2, "warnings": [],
      "data": { "score": 91.2, "method": "PASSIVE", "passed": true, "engine": "…" }
    },
    "ID_VERIFICATION": { "feature": "ID_VERIFICATION", "status": "approved", "score": 98, "warnings": [], "data": { "…": "…" } }
  },
  "decision_reason": "All checks passed",
  "application_id": null,
  "created_at": "2026-07-03T08:00:00+00:00",
  "completed_at": "2026-07-03T08:06:12+00:00",
  "event_type": "identity.kyc.session.approved",
  "idempotency_key": "b2a1…",
  "session": {
    "id": "6f0e2b7a-…",
    "status": "approved",
    "decision_reason": "All checks passed",
    "risk": { "score": 10, "level": "low", "reasons": ["…"], "rules": ["…"], "decision": "approved", "escalated": false },
    "identity": { "full_name": "Sita Sharma", "date_of_birth": "1994-03-12", "document_number": "…", "…": "…" },
    "modules": [
      { "node_id": "ID_VERIFICATION", "feature": "ID_VERIFICATION", "label": "ID Verification",
        "status": "approved", "score": 98, "warnings": [],
        "started_at": "2026-07-03T08:02:10Z", "completed_at": "2026-07-03T08:02:14Z",
        "data": { "fields": { "…": "…" }, "front_image_url": "https://acme.thirdfactor.ai/v3/media/kyc/documents/front/…" },
        "step_status": "completed", "version": null, "edited": false },
      { "node_id": "QUESTIONNAIRE", "feature": "QUESTIONNAIRE", "label": "Questionnaire",
        "status": "approved", "score": 100, "warnings": [],
        "started_at": "2026-07-03T08:03:02Z", "completed_at": "2026-07-03T08:04:40Z",
        "data": { "form_id": "account-purpose", "answers": { "purpose": "savings" }, "…": "…" },
        "step_status": "completed", "version": 2, "edited": true }
    ],
    "media": [
      { "kind": "document", "side": "front", "feature": "ID_VERIFICATION", "node_id": "ID_VERIFICATION",
        "url": "https://acme.thirdfactor.ai/v3/media/kyc/documents/front/…", "content_type": "image/jpeg",
        "source_id": "3c1d9a4e-…", "captured_at": "2026-07-03T08:02:09Z" },
      { "kind": "selfie", "feature": "LIVENESS", "node_id": "LIVENESS",
        "url": "https://acme.thirdfactor.ai/v3/media/kyc/faces/…", "content_type": "image/jpeg",
        "source_id": "7d2e4f60-…", "captured_at": "2026-07-03T08:05:30Z" }
    ],
    "network": { "ip_addresses": [{ "ip": "203.0.113.5", "country": "NP", "is_vpn": false, "…": "…" }],
                 "precise_location": { "latitude": 27.7172, "longitude": 85.324, "…": "…" },
                 "clients": [{ "role": "mobile", "label": "iPhone · Safari", "…": "…" }] },
    "duplicates": [],
    "allow_back": true, "back_count": 1, "edited": true,
    "decision": { "…": "the per-node snapshot, evidence as URLs" },
    "decision_v3": { "id_verifications": ["…"], "liveness_checks": ["…"], "…": "…" },
    "tags": [], "credits_charged": 3.0, "metadata": {}, "…": "…"
  }
}

{
  "payload_version": "2026-05-17",
  "event": "identity.application.manual_review",
  "application": {
    "id": "ge9vgmlmfbi9k5q",
    "external_ref": "core-banking-id-123",
    "tracking_id": "APP-2026-0001",
    "status": "manual_review",
    "decision": "manual_review",
    "flow_id": "savings_v1",
    "current_step_id": "review",
    "created_at": "2026-05-18T08:00:00Z",
    "updated_at": "2026-05-18T08:10:00Z"
  },
  "form_data": {},
  "product": null,
  "sdk_response": {},
  "blocklist_match": {
    "blocklist_id": "90f2c1a8-4f4e-4d1c-9b95-7dfda01965ba",
    "blocklist_name": "Sanctions",
    "block_type": "identifier",
    "value": "123456789",
    "action": "manual_review"
  },
  "created_at": "2026-05-18T08:10:00Z",
  "event_type": "identity.application.manual_review",
  "idempotency_key": "b2a1…"
}

The KYC session payload, field by field

The top-level keys are the original payload and keep their exact shape and values — existing handlers need no change.

Inside session:

Every url is a stable /v3/media/ link on the API host, fetched with your x-api-key — safe to store and fetch later (it stops resolving once evidence retention purges the file). A video's url is null while its WebM is still being produced (status: pending). See Evidence media.

The application envelope, field by field

Headers on every delivery

Designing an idempotent webhook handler

Because delivery is at-least-once, your handler must treat "processed already" as the normal case, not an edge case. The shape that holds up in production:

import express from "express";
import { Pool } from "pg";

const app = express();
const db = new Pool();

app.post(
  "/webhooks/obsidian",
  express.raw({ type: "application/json", limit: "1mb" }), // raw body, not express.json()
  async (req, res) => {
    const sig = req.header("X-Webhook-Signature") ?? "";
    if (!verify(process.env.TF_WEBHOOK_SECRET!, sig, req.body)) {
      return res.status(400).send("bad signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));

    // Ack fast — do the real work after responding.
    res.status(200).end();

    try {
      await handleIdempotently(event);
    } catch (err) {
      // Log and let the delivery fail naturally if you returned non-2xx —
      // here we've already acked, so failures need their own alerting path
      // (dead-letter queue, error tracker) rather than relying on Obsidian's retry.
      console.error("webhook processing failed", event.idempotency_key, err);
    }
  },
);

async function handleIdempotently(event: any) {
  const client = await db.connect();
  try {
    await client.query("BEGIN");

    // Unique constraint on idempotency_key does the real dedupe work —
    // this insert either succeeds once, or throws a unique-violation.
    const inserted = await client.query(
      `INSERT INTO processed_webhooks (idempotency_key, event_type, received_at)
       VALUES ($1, $2, now())
       ON CONFLICT (idempotency_key) DO NOTHING
       RETURNING idempotency_key`,
      [event.idempotency_key, event.event_type],
    );

    if (inserted.rowCount === 0) {
      // Already processed this exact delivery — no-op.
      await client.query("ROLLBACK");
      return;
    }

    // Apply the actual business effect in the same transaction.
    if (event.event_type === "identity.kyc.session.approved") {
      await client.query(
        `UPDATE users SET kyc_status = 'approved' WHERE external_ref = $1`,
        [event.vendor_data],
      );
    }

    await client.query("COMMIT");
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

from fastapi import FastAPI, Request, HTTPException
from sqlalchemy import text
from db import engine  # your SQLAlchemy engine

app = FastAPI()

@app.post("/webhooks/obsidian")
async def receive_webhook(request: Request):
    raw_body = await request.body()
    signature = request.headers.get("X-Webhook-Signature", "")

    if not verify(WEBHOOK_SECRET, signature, raw_body):
        raise HTTPException(status_code=400, detail="bad signature")

    event = await request.json()

    # Ack fast: hand off to a background task/queue and return 200 immediately
    # in real deployments. Shown inline here for clarity.
    handle_idempotently(event)
    return {"ok": True}


def handle_idempotently(event: dict) -> None:
    with engine.begin() as conn:  # one transaction for dedupe + effect
        result = conn.execute(
            text("""
                INSERT INTO processed_webhooks (idempotency_key, event_type, received_at)
                VALUES (:key, :event_type, now())
                ON CONFLICT (idempotency_key) DO NOTHING
                RETURNING idempotency_key
            """),
            {"key": event["idempotency_key"], "event_type": event["event_type"]},
        )
        if result.rowcount == 0:
            return  # already processed this exact delivery

        if event["event_type"] == "identity.kyc.session.approved":
            conn.execute(
                text("UPDATE users SET kyc_status = 'approved' WHERE external_ref = :ref"),
                {"ref": event.get("vendor_data")},
            )

Handling deliveries well

Configuring in the console

1. Open Console → Developers → Webhooks.
2. Set the destination URL. It must be publicly reachable over HTTPS and pass the SSRF guard — private, loopback, link-local, and reserved IP ranges are rejected (both IPv4 and IPv6), redirects are not followed, and a rejected delivery is recorded as failed with the reason for diagnosis.
3. Copy the signing secret and store it in your server config. Rotating it in the console invalidates the previous secret immediately.
4. If your receiver sits behind a gateway that requires credentials, open Authentication (optional) and add a bearer token and/or additional headers — see receiver authentication.
5. Use the test-send button to fire a delivery and confirm your endpoint returns 2xx and verifies the signature.

Troubleshooting

FAQ

Next