Early access: manage your cases from Claude. Find out more →

Developer reference

Outbound Webhook Integration Guide

Push case events from First Mile Labs into Salesforce, HubSpot, Zapier, or any HTTPS endpoint you control. Set up endpoints, verify HMAC signatures, and test delivery end to end.
Push · HMAC-SHA256 signed10 s response budgetJSON Schemas + TypeScript defsIdempotent via eventId
Using Workato? See the Workato recipe for an end-to-end FML → Workato → Salesforce walkthrough. Need to pull them too? The events your endpoints subscribe to are also at GET /v1/events.

Before you begin

Three things to line up before you open the Outbound Webhooks page in the analyst console. Doing them in this order avoids the most common setup mistakes.

  1. Decide who owns the receiver. Pick which system on your side will accept the webhook (Salesforce Apex REST, a Cloud Function in front of HubSpot, a Zapier Catch Raw Hook, or a service you maintain). It must be reachable on the public internet — private/loopback URLs are rejected — and you should give it an HTTPS address.
  2. Have a place to store the shared secret. The secret is shown onceat endpoint creation time. Pick the secret store you'll paste it into (Salesforce Custom Setting, Secrets Manager, environment variable, etc.) before you click Save.
  3. Know which events you want. A full activity-timeline of event types is available — see section 3. Subscribing to fewer events keeps your receiver's load lower and makes the audit log easier to scan. You can change the subscription list any time from the same page.

1. Overview

First Mile Labs sends a POST to every endpoint you register when a case lifecycle event occurs. The event surface is a full activity timeline — case lifecycle, risk and routing decisions, EDD, identity verification, monitoring, per-document processing, person-linking, screening hit triage, outreach, escalation, and ownership changes. Each request is signed with HMAC-SHA256 so your receiver can prove the payload originated from us and was not tampered with in transit.

  • Direction: outbound from First Mile Labs to your system. We never poll your CRM.
  • Transport: give us an HTTPS address, so the payload is encrypted in transit. URLs that resolve to private, loopback, link-local, or cloud-metadata addresses are rejected.
  • Signing: HMAC-SHA256 over the raw request body, sent in X-FML-Signature: sha256=<hex>.
  • Latency budget: your endpoint must respond with 2xx within 10 seconds, or we treat the delivery as failed and schedule a retry.
  • Tenant scope: events are emitted per organisation. Each org configures its own endpoints, secrets, and event subscriptions.

2. Set up an endpoint

Endpoint configuration lives in the analyst console under Compliance Configuration → Outbound Webhooks. You will need analyst-level permissions on your tenant.

  1. Click Add Endpoint. A form appears with URL, label, secret, and event-type fields.
  2. Enter the Endpoint URL. This is the URL of the receiver you control — for example https://your-instance.my.salesforce.com/services/apexrest/fml/webhook. Use an HTTPS address that is reachable from the public internet.
  3. Add a label. Free text such as "Salesforce — production". Used in the dashboard and delivery list.
  4. Provide or generate a shared secret. Leave the field blank to have us generate a 64-character hex secret automatically. The secret is shown once, immediately after creation — copy it into your CRM's secret store at that moment, because we only ever store it encrypted at rest.
  5. Pick the event types you want delivered. By default the full event list is subscribed. Untick any you do not need — for example a finance system may only want case.decision.made. An endpoint with none ticked receives every event.
  6. (Optional) Click Send test ping. Pre-save reachability check — sends an event: "ping" payload to the URL with the secret you supplied, so you can confirm DNS, TLS, and your receiver respond before saving.
  7. Click Add Endpoint at the foot of the form. The endpoint is now active.
One-timeThe shared secret is shown only once at creation. If you lose it you must rotate by editing the endpoint and entering a new value — the previous secret is unrecoverable.

3. Events & payloads

Every payload is JSON. The same envelope wraps every event:

  • event — string, the event type.
  • eventId — UUID v4, unique per event and stable across retries / manual redelivery. Use it as your idempotency key (also exposed as the X-FML-Event-Id header).
  • eventVersion — integer contract version, currently 1. Bumped only on a breaking change; see section 9.
  • timestamp — ISO 8601 UTC, when the event was emitted. It stays the same on every retry and manual redelivery, so don't run a replay window on it: use X-FML-Timestamp (see section 4).
  • orgId — your First Mile Labs organisation identifier.
  • crmRecordId — present whenever caseId is present. Echoes back the crmRecordId your CRM sent when it created the case with POST /v1/cases, so you can update the right record without a lookup. null if the case has none.

The envelope is then merged with the event-specific fields below. Example for case.decision.made:

{
  "event": "case.decision.made",
  "eventId": "0d4e6b3c-9e4f-4a4a-b3a1-3f6f8c9b1a22",
  "eventVersion": 1,
  "timestamp": "2026-05-14T09:18:42.117Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "outcome": "approved",
  "notes": "All documentation verified. UBO IDV passed.",
  "analystEmail": "alex.kim@demobank.com",
  "decidedAt": "2026-05-14T09:18:42.052Z",
  "companyName": "Acme Holdings Ltd"
}

HTTP request headers on every delivery:

  • Content-Type: application/json
  • X-FML-Signature: sha256=<hex> — HMAC-SHA256 of the raw body, computed with your endpoint's shared secret.
  • X-FML-Event: <event-type> — convenience header so receivers can route without parsing the body first.
  • X-FML-Event-Id: <uuid> — stable across retries and manual redelivery, and a copy of eventId in the body. That is your idempotency key. Read it from the body where you can: the body is signed and the headers are not.
  • X-FML-Event-Version: 1 — contract version. We bump it only on a breaking change to the envelope or signature scheme; see section 9.
  • X-FML-Timestamp: <ISO 8601> — the emission time, the same as timestamp in the body, until a request goes out more than 4 minutes after the event. From then on it is the time of sending, so a late retry or manual redelivery still passes a replay window. Use it to enforce one (we recommend 5 minutes).
  • X-FML-Delivery-Id: <int> — internal delivery row id, useful when you want to ask our support team to look up a specific failed delivery. Stable across retries.
  • X-FML-Attempt: <n> — 1-indexed attempt counter. 1 on the initial try, 2 on the first automatic retry, and so on; manual redeliveries continue to increment from the same delivery row rather than resetting.
  • User-Agent: FirstMileLabs-Webhooks/1.0

Each event type and its payload fields:

CodegenMany of the events below also have a machine-readable JSON Schema (Draft 2020-12) you can point an iPaaS connector or stub-code generator at. Not every event has one yet: the index at /schemas/webhooks/index.json lists those that do, and their cards carry a Schema link. Schemas are versioned (.v1.json); a future eventVersion bump will ship a .v2.json alongside without breaking consumers.
TypeScriptHand-rolled Node/TypeScript receiver? Drop our ready-made ambient definitions into your project and switch on the event field with full type narrowing — no codegen required: webhooks.d.ts ↓ (manifest at /types/index.json). The file exports one interface per event that has a schema (CaseCreatedV1, CaseDecisionMadeV1, …), a discriminated union FmlWebhookEvent, and a lookup map FmlWebhookEventMap. Regenerated from the JSON Schemas on every build, so it never drifts.
case.createdEventSchema (v1) ↗

A new case is opened — manual analyst creation, customer doc upload, application form submission, or POST /v1/cases.

FieldTypeNotes
caseIdstringFirst Mile Labs case identifier, a UUID.
companyNamestring | nullSubject company name when known.
companyNumberstring | nullRegistry number when collected (e.g. Companies House number).
countrystring | nullISO country / jurisdiction of the subject company.
customerEmailstring | nullEmail of the customer the case belongs to.
sourcestringOne of "manual", "doc_upload", "application_form", or "api" for a case created through POST /v1/cases.
createdBystringAnalyst email on manual creation, or "client:<clientId>" on a case created through the API. Absent otherwise.

Sample payload

{
  "event": "case.created",
  "timestamp": "2026-05-14T09:18:42.117Z",
  "orgId": "org_demo_bank",
  "crmRecordId": null,
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "companyNumber": "12345678",
  "country": "GB",
  "customerEmail": "ops@acmeholdings.example",
  "source": "manual",
  "createdBy": "alex.kim@demobank.com"
}
case.submittedEventSchema (v1) ↗

The customer has finished their part — application form submitted or customer review confirmed.

FieldTypeNotes
caseIdstring—
companyNamestring | null—
countrystring | null—
customerEmailstring | null—
sourcestring"application_form" or "doc_upload".

Sample payload

{
  "event": "case.submitted",
  "timestamp": "2026-05-14T09:22:11.482Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "country": "GB",
  "customerEmail": "ops@acmeholdings.example",
  "source": "application_form"
}
case.decision.madeEventSchema (v1) ↗

An analyst has approved or declined the case, or your decision policy has: an auto-approval, an auto-rejection, or the age gate declining an underage customer.

FieldTypeNotes
caseIdstring—
outcomestring"approved" or "declined".
notesstringFree-text decision notes captured in the analyst panel, or why the platform decided.
analystEmailstringAnalyst who made the decision, or "policy_engine" for an automatic decision.
decidedAtstring (ISO 8601)Decision timestamp.
companyNamestring | null—
autobooleantrue on an automatic decision; absent on an analyst's.
reasonstringOnly on an automatic decision: "policy_engine" (your decision policy) or "age_gate".

Sample payload

{
  "event": "case.decision.made",
  "timestamp": "2026-05-14T11:04:08.961Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "outcome": "approved",
  "notes": "All documentation verified. UBO IDV passed.",
  "analystEmail": "alex.kim@demobank.com",
  "decidedAt": "2026-05-14T11:04:08.901Z",
  "companyName": "Acme Holdings Ltd"
}
case.status.changedEventSchema (v1) ↗

Lifecycle transitions — initial submission, decision, escalation to senior, return from senior review, and a customer’s exit: "exited" when it ends (with case.exit.ended), and "approved" again when one is reversed (with case.exit.reversed).

FieldTypeNotes
caseIdstring—
companyNamestring | nullAbsent on an exit’s change.
statusstringNew status (e.g. "approved", "declined", "pending_senior", "returned", "exited").
previousStatusstringStatus before the transition.
changedBystring | nullEmail of the actor (analyst or customer), or "policy_engine" for an automatic decision. Null on an exit’s change, which names nobody.
recommendationstringSenior reviewer recommendation — only on returns from senior review.
exitIdstring (UUID)Only on an exit’s change: the exit, as in the case.exit.* events.
ledBystringOnly on an exit’s change: "customer" or "firm".

Sample payload

{
  "event": "case.status.changed",
  "timestamp": "2026-05-14T11:04:09.014Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "status": "approved",
  "previousStatus": "awaiting-decision",
  "changedBy": "alex.kim@demobank.com"
}
data.correctedEventSchema (v1) ↗

A customer corrected extracted data during review, or an analyst manually overrode an errored document (approve / escalate).

FieldTypeNotes
caseIdstring—
sourcestring"customer_review" or "analyst_override".
amendmentCountnumberCustomer review only — number of fields the customer changed.
amendmentsarrayCustomer review only — array of {section, field, originalValue, correctedValue} entries.
documentIdnumberAnalyst override only — the document that was overridden.
fieldstringAnalyst override only — always "document_status".
originalValuestringAnalyst override only — typically "error".
correctedValuestringAnalyst override only — "approved" or "escalated".
notestringManual approval note.
reasonstringEscalation reason.
bystringAnalyst email.

Sample payload

{
  "event": "data.corrected",
  "timestamp": "2026-05-14T09:24:55.220Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "source": "customer_review",
  "amendmentCount": 2,
  "amendments": [
    {
      "section": "company",
      "field": "registeredAddress",
      "originalValue": "10 High Street, London EC1A 1AA",
      "correctedValue": "10 High Street, London EC1A 1BB"
    },
    {
      "section": "directors",
      "field": "0.fullName",
      "originalValue": "J Smith",
      "correctedValue": "Jane Smith"
    }
  ]
}
document.uploadedEventSchema (v1) ↗

One or more documents were uploaded to a case (single emit per upload batch).

FieldTypeNotes
caseIdstring—
documentIdsnumber[]Internal IDs of every uploaded document.
fileCountnumberNumber of files in the batch.
filenamesstring[]Original filenames.

Sample payload

{
  "event": "document.uploaded",
  "timestamp": "2026-05-14T09:19:30.005Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "documentIds": [4711, 4712, 4713],
  "fileCount": 3,
  "filenames": [
    "certificate-of-incorporation.pdf",
    "register-of-directors.pdf",
    "passport-jane-smith.jpg"
  ]
}
screening.completedEventSchema (v1) ↗

A sanctions / PEP / adverse media screening run finished for a case.

FieldTypeNotes
caseIdstring—
screenednumberTotal subjects screened (company plus directors and shareholders).
summaryarrayArray of {name, role, status} — status is "clear", "match", "pep", or "sanctioned".
timestampstring (ISO 8601)When screening completed.

Sample payload

{
  "event": "screening.completed",
  "timestamp": "2026-05-14T09:25:14.770Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "screened": 3,
  "summary": [
    { "name": "Acme Holdings Ltd", "role": null,          "status": "clear" },
    { "name": "Jane Smith",        "role": "director",    "status": "clear" },
    { "name": "Maria Lopez",       "role": "shareholder", "status": "pep"   }
  ]
}
ai_review.completedEventSchema (v1) ↗

The autonomous AI case review (AI screening) finished for a case — fired both for analyst-triggered streaming reviews and for background reviews kicked off automatically after form submission or customer review confirmation.

FieldTypeNotes
caseIdstring—
reviewIdnumberInternal id of the case_ai_reviews row.
companyNamestring | null—
triggeredBystringAnalyst email for analyst-triggered streaming runs (e.g. "alex.kim@demobank.com"), or a "system:form-submission:<email>" / "system:confirm-review:<email>" tag for background runs kicked off automatically.
recommendationstringAI recommendation — one of "Approve", "Refer", or "Decline".
confidencestringModel confidence in the recommendation — one of "High", "Medium", or "Low".
riskFactorCountnumberNumber of risk factors the AI surfaced.
riskFactorsarrayArray of {text, severity} where severity is "HIGH", "MEDIUM", or "LOW".
completedAtstring (ISO 8601)When the AI review finished.

Sample payload

{
  "event": "ai_review.completed",
  "timestamp": "2026-05-14T09:31:02.418Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reviewId": 8421,
  "companyName": "Acme Holdings Ltd",
  "triggeredBy": "alex.kim@demobank.com",
  "recommendation": "Approve",
  "confidence": "High",
  "riskFactorCount": 2,
  "riskFactors": [
    { "text": "UBO Maria Lopez returned a PEP screening hit pending adjudication", "severity": "MEDIUM" },
    { "text": "Company registered less than 12 months ago",                       "severity": "LOW"    }
  ],
  "completedAt": "2026-05-14T09:31:02.301Z"
}
document.processedEvent

A single uploaded document finished AI extraction successfully (one emit per document, complement of the batch document.uploaded).

FieldTypeNotes
caseIdstring—
documentIdnumberInternal id of the documents row.
documentTypestringAI-classified document type, e.g. "Certificate of Incorporation".
filenamestringOriginal filename as uploaded.
statusstringAlways "complete" — error completions do not fire this event.
confidencestring"High", "Medium", or "Low".
warningCountnumberNumber of AI warnings on the extraction.
missingFieldCountnumberNumber of expected fields the AI could not extract.

Sample payload

{
  "event": "document.processed",
  "timestamp": "2026-05-14T09:19:48.221Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "documentId": 4711,
  "documentType": "Certificate of Incorporation",
  "filename": "certificate-of-incorporation.pdf",
  "status": "complete",
  "confidence": "High",
  "warningCount": 0,
  "missingFieldCount": 0
}
risk.assessedEvent

The risk-scoring engine produced (or refreshed) a composite score for a case.

FieldTypeNotes
caseIdstring—
assessmentIdnumberInternal id of the risk_assessments row.
configIdnumberActive risk_model_config row this score was computed against.
compositeScorenumber0–100 composite score.
bandIdstringRisk band — "low", "medium", "high", "prohibited". An approved override's band while one is in force.
bandLabelstringHuman-readable band label.
computedBandIdstring | nullThe band the engine computed, when an approved override replaced it; else null.
computedBandLabelstring | nullIts label.
riskOverrideIdstring | nullThe approved override in force, if any.
causestring | nullWhat led to a re-score, when the platform knows: for example "screening_ruling", or "model_changed" for a score recalculated after your risk model changed.
causedBystring | nullWho did it.
modelVersionnumber | nullThe version of your risk model the case was scored on. Null for a model saved on the Risk Model page, which has no version number.
modelVersionMadeLiveBystring | nullWho made that version live.
modelVersionReasonstring | nullThe reason given when that version was a change made by hand; else null.
assessedBystring"system" for automatic runs, analyst email for manual recompute.
assessedAtstring (ISO 8601)When the score was committed.

Sample payload

{
  "event": "risk.assessed",
  "timestamp": "2026-05-14T09:32:11.005Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "assessmentId": 3301,
  "configId": 7,
  "compositeScore": 27,
  "bandId": "low",
  "bandLabel": "Low",
  "assessedBy": "system",
  "assessedAt": "2026-05-14T09:32:10.992Z"
}
routing.evaluatedEvent

A decision-policy run completed for a case (every time the rule engine evaluates the active policy).

FieldTypeNotes
caseIdstring—
policyIdnumberActive decision_policies row id.
policyNamestringHuman-readable name of the policy that was matched.
matchedRuleIndexnumber | nullZero-indexed rule that matched, or null if the default branch fired or a platform rule overrode the policy.
overrideReasonstring | nullWhy a platform rule overrode the policy, for example a company whose registry check did not pass. Null otherwise; absent on an age-gate rejection.
outcomestring"AUTO_APPROVE", "MANUAL_REVIEW" or "REJECT". REJECT is the policy’s recommendation to decline: a policy never declines a case itself, so an analyst decides, and case.decision.made follows their decision. Only an age-gate rejection is a decision in itself.
evaluatedAtstring (ISO 8601)—

Sample payload

{
  "event": "routing.evaluated",
  "timestamp": "2026-05-14T09:32:11.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "policyId": 4,
  "policyName": "EU MSB — standard routing",
  "matchedRuleIndex": 1,
  "overrideReason": null,
  "outcome": "REVIEW_LEVEL_1",
  "evaluatedAt": "2026-05-14T09:32:11.110Z"
}
edd.requirements.changedEvent

An analyst marked an Enhanced Due Diligence requirement outstanding/received/waived (or updated its note).

FieldTypeNotes
caseIdstring—
reqKeystringStable key for the requirement (e.g. "source_of_funds").
labelstringHuman-readable requirement label.
statusstring"outstanding", "received", or "waived".
previousStatusstring | nullStatus before the change.
notestringFree-text analyst note.
updatedBystringAnalyst email.

Sample payload

{
  "event": "edd.requirements.changed",
  "timestamp": "2026-05-14T10:14:02.331Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reqKey": "source_of_funds",
  "label": "Source of Funds evidence",
  "status": "received",
  "previousStatus": "outstanding",
  "note": "Bank statement received and reviewed.",
  "updatedBy": "alex.kim@demobank.com"
}
edd.requestedEvent

An EDD evidence-request email was sent to the customer (one emit per send).

FieldTypeNotes
caseIdstring—
recipientEmailstring—
itemCountnumber—
itemsarrayArray of {key, label} for each outstanding EDD item included in the email.
sentBystringAnalyst email.
sentAtstring (ISO 8601)—

Sample payload

{
  "event": "edd.requested",
  "timestamp": "2026-05-14T10:18:55.770Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "recipientEmail": "ops@acmeholdings.example",
  "itemCount": 2,
  "items": [
    { "key": "source_of_funds",  "label": "Source of Funds evidence" },
    { "key": "source_of_wealth", "label": "Source of Wealth — UBO Maria Lopez" }
  ],
  "sentBy": "alex.kim@demobank.com",
  "sentAt": "2026-05-14T10:18:55.701Z"
}
idv.dispatchedEvent

An identity-verification (Didit) link was sent to a real person on the case (one emit per email — deduped by personKey across roles).

FieldTypeNotes
caseIdstring—
recipientEmailstring—
recipientNamestring—
personKeystringStable identity key (UUID v4) shared across the same real human within the case.
rolesstring[]All roles this dispatch covers (e.g. ["director", "ubo"]).
dispatchedBystring"system" for automatic dispatch, analyst email for manual sends.

Sample payload

{
  "event": "idv.dispatched",
  "timestamp": "2026-05-14T09:25:18.220Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "recipientEmail": "jane.smith@example.com",
  "recipientName": "Jane Smith",
  "personKey": "00000000-0000-0000-0000-000000000001",
  "roles": ["director", "ubo"],
  "dispatchedBy": "system"
}
idv.completedEvent

A check on the case was recorded. Despite its name, this isn’t only an identity check’s result: it is sent each time the platform runs a check and records the outcome, for any kind of check (the company’s registry check and each person’s identity check among them) and whichever provider ran it. An identity check the person completes with the provider is reported when it starts, with outcome "pending".

FieldTypeNotes
caseIdstring—
verificationTypestringThe kind of check, for example "registry" or "identity".
vendorNamestringThe provider that ran the check, as it is named in your provider set-up. "Not configured" when a registry check has no provider set up.
positionnumberThe provider’s position in your set-up for that kind of check. On an identity check, that position × 100 plus the person’s index among the people being verified, so each person has their own.
rolestringThe provider’s role in your set-up, "required" or "fallback". Not the person’s role on the case.
outcomestringWhat was recorded, for example "pass", "fail", "pending" (waiting on the person), "unavailable" (no provider is set up, or the provider doesn’t cover this subject), "skipped" (a fallback that wasn’t needed, or a check that doesn’t apply) or "error" (the check couldn’t be run). Treat a value you don’t know as not passed.
errorMessagestring | nullFixed text, "The check could not be completed.", when the check couldn’t be run. It never gives the reason. Null or absent otherwise.
completedAtstring (ISO 8601)When the outcome was recorded.

Sample payload

{
  "event": "idv.completed",
  "timestamp": "2026-05-14T09:48:02.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "verificationType": "identity",
  "vendorName": "Example Provider",
  "position": 100,
  "role": "required",
  "outcome": "pass",
  "errorMessage": null,
  "completedAt": "2026-05-14T09:48:02.001Z"
}
idv.satisfied_by_documentEvent

A Didit dispatch was suppressed because an accepted Passport/ID document is already on file for that person — the IDV slot is satisfied without an email.

FieldTypeNotes
caseIdstring—
personNamestring—
personEmailstring | null—
personKeystring—
rolesstring[]—
satisfiedByDocIdnumberInternal id of the Passport/ID document that satisfied IDV.

Sample payload

{
  "event": "idv.satisfied_by_document",
  "timestamp": "2026-05-14T09:21:11.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "personName": "Jane Smith",
  "personEmail": "jane.smith@example.com",
  "personKey": "00000000-0000-0000-0000-000000000001",
  "roles": ["director"],
  "satisfiedByDocId": 4713
}
monitoring.alert.createdEvent

A perpetual-monitoring run produced a new alert against an existing case.

FieldTypeNotes
caseIdstring—
companyNamestring | null—
runIdnumberInternal id of the monitoring run that produced the alert.
alertTypestringAlert category, e.g. "sanctions_hit" (a sanctions or PEP match), "structure_change" or "document_expiry".
severitystring"low", "medium", "high" or "critical".
titlestringShort alert title.
detailstringLonger alert detail.

Sample payload

{
  "event": "monitoring.alert.created",
  "timestamp": "2026-05-14T03:00:14.880Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "runId": 5001,
  "alertType": "sanctions_hit",
  "severity": "high",
  "title": "New OpenSanctions hit — Maria Lopez",
  "detail": "PEP designation added since last screening run."
}
monitoring.run.completedEvent

A perpetual-monitoring run finished for a case (regardless of whether any alerts were generated).

FieldTypeNotes
caseIdstring—
runIdnumber—
triggeredBystring"scheduled" or analyst email for ad-hoc runs.
alertsGeneratednumberNumber of new alerts produced by this run.
checksRunarrayArray of {check, status, subjects} per check that ran. status is "ok", "skipped" (with why in reason) or "error" (with the reason in error), or "not_found" when the registry refresh could not find the company at the registry. When the registry refresh found the company by its registration number, its "ok" entry carries that number as registrationNumber.

Sample payload

{
  "event": "monitoring.run.completed",
  "timestamp": "2026-05-14T03:00:15.001Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "runId": 5001,
  "triggeredBy": "scheduled",
  "alertsGenerated": 1,
  "checksRun": [
    { "check": "sanctions",     "status": "ok", "subjects": 3 },
    { "check": "adverse_media", "status": "skipped", "reason": "no_adverse_media_source" }
  ]
}
monitoring.review.openedEventSchema (v1) ↗

A monitoring alert on one of a customer’s UBOs, directors or intermediary entities opened a review case. Once per review — a repeat of the same alert while the review is open attaches to it and is reported by monitoring.alert.created alone.

FieldTypeNotes
caseIdstringThe monitored customer’s case — the record your CRM holds. Never the review case.
reviewCaseIdstring (UUID)The review. Stable across every event for the same review.
reviewRefstring | nullHuman-readable review reference, e.g. "REV-2026-00012".
alertTypestringThe monitoring alert that opened the review, e.g. "sanctions_hit".
severitystring | null"low", "medium", "high" or "critical".
subjectRolestring | nullThe flagged party’s role, e.g. "UBO" or "Director". Never their name.
subjectRefstring | nullWhere the flagged party sits in the case’s ownership data, e.g. "ubo_0".
personIdnumber | nullPerson-registry id of the flagged party, when linked.
occurrenceNonumber2 or more means this same fact has been reviewed on this customer before.
statestringAlways "open".
sourcestring | nullWhat raised the alert, e.g. "scheduled".
priorDispositionstring | nullThe verdict on the previous occurrence of this fact, e.g. "false_positive". Null the first time.

Sample payload

{
  "event": "monitoring.review.opened",
  "timestamp": "2026-05-14T03:00:16.204Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reviewCaseId": "3f2a8c1e-6b4d-4e8a-9c21-5d7e0f1a2b3c",
  "reviewRef": "REV-2026-00012",
  "alertType": "sanctions_hit",
  "severity": "critical",
  "subjectRole": "UBO",
  "subjectRef": "ubo_0",
  "personId": null,
  "occurrenceNo": 1,
  "state": "open",
  "source": "scheduled",
  "priorDisposition": null
}
monitoring.review.dispositionedEventSchema (v1) ↗

An analyst reached a verdict on a review. Sent before its consequences, so the risk re-score (risk.assessed) and any MLRO hand-off (monitoring.review.escalated) follow it.

FieldTypeNotes
caseIdstringThe monitored customer’s case — the record your CRM holds. Never the review case.
reviewCaseIdstring (UUID)The review. Stable across every event for the same review.
reviewRefstring | nullHuman-readable review reference, e.g. "REV-2026-00012".
alertTypestringThe monitoring alert that opened the review, e.g. "sanctions_hit".
severitystring | null"low", "medium", "high" or "critical".
subjectRolestring | nullThe flagged party’s role, e.g. "UBO" or "Director". Never their name.
subjectRefstring | nullWhere the flagged party sits in the case’s ownership data, e.g. "ubo_0".
personIdnumber | nullPerson-registry id of the flagged party, when linked.
occurrenceNonumber2 or more means this same fact has been reviewed on this customer before.
dispositionstring"true_match", "false_positive" or "escalate".
dispositionBystring | nullAnalyst email.
isReversalbooleanTrue when this confirms a match a previous occurrence dismissed as a false positive.
statestring"pending_approval" (awaiting a second person) or "with_mlro".

Sample payload

{
  "event": "monitoring.review.dispositioned",
  "timestamp": "2026-05-14T10:12:40.551Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reviewCaseId": "3f2a8c1e-6b4d-4e8a-9c21-5d7e0f1a2b3c",
  "reviewRef": "REV-2026-00012",
  "alertType": "sanctions_hit",
  "severity": "critical",
  "subjectRole": "UBO",
  "subjectRef": "ubo_0",
  "personId": null,
  "occurrenceNo": 1,
  "disposition": "true_match",
  "dispositionBy": "alex.kim@demobank.com",
  "isReversal": false,
  "state": "pending_approval"
}
monitoring.review.escalatedEventSchema (v1) ↗

A review was handed to the MLRO for senior review. Pairs with the escalation.created event on the same customer case, and adds which review and why.

FieldTypeNotes
caseIdstringThe monitored customer’s case — the record your CRM holds. Never the review case.
reviewCaseIdstring (UUID)The review. Stable across every event for the same review.
reviewRefstring | nullHuman-readable review reference, e.g. "REV-2026-00012".
alertTypestringThe monitoring alert that opened the review, e.g. "sanctions_hit".
severitystring | null"low", "medium", "high" or "critical".
subjectRolestring | nullThe flagged party’s role, e.g. "UBO" or "Director". Never their name.
subjectRefstring | nullWhere the flagged party sits in the case’s ownership data, e.g. "ubo_0".
personIdnumber | nullPerson-registry id of the flagged party, when linked.
occurrenceNonumber2 or more means this same fact has been reviewed on this customer before.
escalationReasonstring"analyst_escalate" (the analyst could not call it), "band_increase" (a confirmed match raised the risk band) or "model_drift" (an all-false-positive close re-scored on the current model and the band still moved).
escalationIdnumber | null—
assignedTostring | nullThe MLRO it was assigned to. Null when none is nominated and it waits in the senior queue.
bandBeforestring | null—
bandAfterstring | null—

Sample payload

{
  "event": "monitoring.review.escalated",
  "timestamp": "2026-05-14T10:12:41.093Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reviewCaseId": "3f2a8c1e-6b4d-4e8a-9c21-5d7e0f1a2b3c",
  "reviewRef": "REV-2026-00012",
  "alertType": "sanctions_hit",
  "severity": "critical",
  "subjectRole": "UBO",
  "subjectRef": "ubo_0",
  "personId": null,
  "occurrenceNo": 1,
  "escalationReason": "band_increase",
  "escalationId": 3001,
  "assignedTo": "mlro@demobank.com",
  "bandBefore": "Medium",
  "bandAfter": "High"
}
monitoring.review.closedEventSchema (v1) ↗

A second person approved the verdict and closed the review.

FieldTypeNotes
caseIdstringThe monitored customer’s case — the record your CRM holds. Never the review case.
reviewCaseIdstring (UUID)The review. Stable across every event for the same review.
reviewRefstring | nullHuman-readable review reference, e.g. "REV-2026-00012".
alertTypestringThe monitoring alert that opened the review, e.g. "sanctions_hit".
severitystring | null"low", "medium", "high" or "critical".
subjectRolestring | nullThe flagged party’s role, e.g. "UBO" or "Director". Never their name.
subjectRefstring | nullWhere the flagged party sits in the case’s ownership data, e.g. "ubo_0".
personIdnumber | nullPerson-registry id of the flagged party, when linked.
occurrenceNonumber2 or more means this same fact has been reviewed on this customer before.
dispositionstring"true_match", "false_positive" or "escalate".
dispositionBystring | nullWho reached the verdict.
approvedBystring | nullWho closed it — a different person while four-eyes is on.
approvedAtstring (ISO 8601) | null—
bandBeforestring | nullThe customer’s risk band before this review re-scored it, when it did.
bandAfterstring | null—
bandReaffirmedbooleanTrue when this close — the last open review, all false positives — re-checked the band on the current risk model.

Sample payload

{
  "event": "monitoring.review.closed",
  "timestamp": "2026-05-14T15:40:02.310Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reviewCaseId": "3f2a8c1e-6b4d-4e8a-9c21-5d7e0f1a2b3c",
  "reviewRef": "REV-2026-00012",
  "alertType": "sanctions_hit",
  "severity": "critical",
  "subjectRole": "UBO",
  "subjectRef": "ubo_0",
  "personId": null,
  "occurrenceNo": 1,
  "disposition": "true_match",
  "dispositionBy": "alex.kim@demobank.com",
  "approvedBy": "sam.patel@demobank.com",
  "approvedAt": "2026-05-14T15:40:02.301Z",
  "bandBefore": "Medium",
  "bandAfter": "High",
  "bandReaffirmed": false
}
monitoring.review.reopenedEventSchema (v1) ↗

A closed review was reopened. Its verdict and sign-off are cleared, so it needs a fresh decision and a fresh second person.

FieldTypeNotes
caseIdstringThe monitored customer’s case — the record your CRM holds. Never the review case.
reviewCaseIdstring (UUID)The review. Stable across every event for the same review.
reviewRefstring | nullHuman-readable review reference, e.g. "REV-2026-00012".
alertTypestringThe monitoring alert that opened the review, e.g. "sanctions_hit".
severitystring | null"low", "medium", "high" or "critical".
subjectRolestring | nullThe flagged party’s role, e.g. "UBO" or "Director". Never their name.
subjectRefstring | nullWhere the flagged party sits in the case’s ownership data, e.g. "ubo_0".
personIdnumber | nullPerson-registry id of the flagged party, when linked.
occurrenceNonumber2 or more means this same fact has been reviewed on this customer before.
reopenedBystring | null—
previousDispositionstring | nullThe verdict that was cleared.

Sample payload

{
  "event": "monitoring.review.reopened",
  "timestamp": "2026-05-20T09:05:11.777Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "reviewCaseId": "3f2a8c1e-6b4d-4e8a-9c21-5d7e0f1a2b3c",
  "reviewRef": "REV-2026-00012",
  "alertType": "sanctions_hit",
  "severity": "critical",
  "subjectRole": "UBO",
  "subjectRef": "ubo_0",
  "personId": null,
  "occurrenceNo": 1,
  "reopenedBy": "mlro@demobank.com",
  "previousDisposition": "false_positive"
}
case.exit.confirmedEventEarly accessSchema (v1) ↗

A customer’s exit was decided: a firm-led exit confirmed by an MLRO or above, or one the customer led recorded, in the app or through POST /v1/cases/{caseId}/exit. Nothing is sent before then: a proposed exit, or one cancelled before it was confirmed, sends nothing. The customer stays approved, and monitored, until endOn. Customer exits have to be switched on for your workspace: without them no exit is recorded, so this event is never sent.

FieldTypeNotes
caseIdstringThe customer’s case.
exitIdstring (UUID)The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns.
ledBystring"customer" (they asked to leave, or stopped trading) or "firm".
endOnstring (YYYY-MM-DD)The day the relationship ends. The record-keeping clock starts on it.
statestringAlways "confirmed".
confirmedAtstring (ISO 8601)When it was confirmed or recorded.

Sample payload

{
  "event": "case.exit.confirmed",
  "timestamp": "2026-11-10T14:02:31.448Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "exitId": "7b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "ledBy": "firm",
  "endOn": "2027-02-08",
  "state": "confirmed",
  "confirmedAt": "2026-11-10T14:02:31.402Z"
}
case.exit.endedEventEarly accessSchema (v1) ↗

The exit’s end date came and it ended: the case is exited, and case.status.changed is sent with it, status "exited" (in no set order: match them on exitId). It ends on its end date, by the nightly run or in the app, once nothing open on the case stops it. Customer exits have to be switched on for your workspace: without them no exit is recorded, so this event is never sent.

FieldTypeNotes
caseIdstringThe customer’s case.
exitIdstring (UUID)The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns.
ledBystring"customer" (they asked to leave, or stopped trading) or "firm".
endOnstring (YYYY-MM-DD)The day the relationship ends. The record-keeping clock starts on it.
statestringAlways "ended".
endedAtstring (ISO 8601)When it ended. Later than endOn when something on the case held the end back; the record-keeping clock still runs from endOn.

Sample payload

{
  "event": "case.exit.ended",
  "timestamp": "2027-02-08T00:30:04.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "exitId": "7b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "ledBy": "firm",
  "endOn": "2027-02-08",
  "state": "ended",
  "endedAt": "2027-02-08T00:30:04.093Z"
}
case.exit.cancelledEventEarly accessSchema (v1) ↗

A confirmed exit was cancelled before it ended. The customer stays approved. Sent only for an exit you were told was confirmed. Customer exits have to be switched on for your workspace: without them no exit is recorded, so this event is never sent.

FieldTypeNotes
caseIdstringThe customer’s case.
exitIdstring (UUID)The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns.
ledBystring"customer" (they asked to leave, or stopped trading) or "firm".
endOnstring (YYYY-MM-DD)The day the relationship ends. The record-keeping clock starts on it.
statestringAlways "cancelled".
cancelledAtstring (ISO 8601)—

Sample payload

{
  "event": "case.exit.cancelled",
  "timestamp": "2026-11-24T10:15:52.730Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "exitId": "7b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "ledBy": "firm",
  "endOn": "2027-02-08",
  "state": "cancelled",
  "cancelledAt": "2026-11-24T10:15:52.691Z"
}
case.exit.reversedEventEarly accessSchema (v1) ↗

An ended exit was reversed, because ending it was a mistake: confirmed by an MLRO or above within 30 days of the day it ended. The case is approved again, and case.status.changed is sent with it, status "approved". Customer exits have to be switched on for your workspace: without them no exit is recorded, so this event is never sent.

FieldTypeNotes
caseIdstringThe customer’s case.
exitIdstring (UUID)The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns.
ledBystring"customer" (they asked to leave, or stopped trading) or "firm".
endOnstring (YYYY-MM-DD)The day the relationship ends. The record-keeping clock starts on it.
statestringAlways "reversed".
endedAtstring (ISO 8601) | nullWhen the exit had ended.
reversedAtstring (ISO 8601)—

Sample payload

{
  "event": "case.exit.reversed",
  "timestamp": "2027-02-15T11:40:09.317Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "exitId": "7b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "ledBy": "firm",
  "endOn": "2027-02-08",
  "state": "reversed",
  "endedAt": "2027-02-08T00:30:04.093Z",
  "reversedAt": "2027-02-15T11:40:09.280Z"
}
document_request.createdEventSchema (v1) ↗

A case’s customer was asked for what they still owe: from the app, by the platform (a trigger, or an expired link sent again), or through POST /v1/cases/{caseId}/document-requests. A request to someone a request is still open to joins it: joined is true, and the customer keeps one link for everything.

FieldTypeNotes
caseIdstringThe customer’s case.
requestIdintegerThe request. Stable across its events, and what POST /v1/cases/{caseId}/document-requests returns. GET /v1/cases/{caseId}/document-requests has each item in full.
itemCountinteger—
itemsobject[]Each item: index, category, docType, eddReqKey (sow_person for a person’s Source of Wealth), personRef, status (pending, uploaded, declared, cannot_provide or not_applicable) and documentIds. Never a person’s name, the customer’s words or the upload link.
deliverystring"email": we emailed the customer. "link": the link went back to your API call, for you to send.
sourcestring"app", "api" or "automatic".
joinedbooleanThe items joined a request already open to the same person.
addedCountintegerHow many items were new to the request.
expiresAtstring (ISO 8601)When its link stops working.

Sample payload

{
  "event": "document_request.created",
  "timestamp": "2026-11-17T09:12:44.610Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "requestId": 1287,
  "delivery": "link",
  "source": "api",
  "joined": false,
  "addedCount": 2,
  "itemCount": 2,
  "expiresAt": "2026-12-17T09:12:44.512Z",
  "items": [
    { "index": 0, "category": "Missing Document", "docType": "Register of Shareholders", "eddReqKey": null, "personRef": null, "status": "pending", "documentIds": [] },
    { "index": 1, "category": "Source of Wealth", "docType": null, "eddReqKey": "sow_person", "personRef": "ubo_0", "status": "pending", "documentIds": [] }
  ]
}
document_request.submittedEventSchema (v1) ↗

The customer submitted the request. Items they sent, declared or said they can’t provide count as answered; the rest are pending, for you to chase with another request.

FieldTypeNotes
caseIdstringThe customer’s case.
requestIdintegerThe request. Stable across its events, and what POST /v1/cases/{caseId}/document-requests returns. GET /v1/cases/{caseId}/document-requests has each item in full.
itemCountinteger—
itemsobject[]Each item: index, category, docType, eddReqKey (sow_person for a person’s Source of Wealth), personRef, status (pending, uploaded, declared, cannot_provide or not_applicable) and documentIds. Never a person’s name, the customer’s words or the upload link.
submittedAtstring (ISO 8601)—
uploadedCountintegerItems with documents.
declaredCountintegerPeople’s Source of Wealth declared.
answeredCountintegerItems they said they can’t provide, or that don’t apply. Their reasons are on the case, and in GET /v1/cases/{caseId}/document-requests.
pendingCountintegerItems still owed.

Sample payload

{
  "event": "document_request.submitted",
  "timestamp": "2026-11-18T16:40:02.117Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "requestId": 1287,
  "submittedAt": "2026-11-18T16:40:02.090Z",
  "itemCount": 2,
  "uploadedCount": 1,
  "declaredCount": 0,
  "answeredCount": 1,
  "pendingCount": 0,
  "items": [
    { "index": 0, "category": "Missing Document", "docType": "Register of Shareholders", "eddReqKey": null, "personRef": null, "status": "uploaded", "documentIds": [90211, 90212] },
    { "index": 1, "category": "Source of Wealth", "docType": null, "eddReqKey": "sow_person", "personRef": "ubo_0", "status": "cannot_provide", "documentIds": [] }
  ]
}
screening.hit.detectedEventSchema (v1) ↗

A new sanctions/PEP screening hit was persisted (onboarding screening, source="screening") or surfaced by ComplyAdvantage native ongoing monitoring (source="comply_advantage_native"). Fires once per genuinely-new hit. Pair with screening.hit.triaged on (caseId, hitId) for the AI verdict; close the loop with POST /v1/cases/{caseId}/screening/disposition.

FieldTypeNotes
caseIdstring—
hitIdstringHit identifier — raw vendor id, or "ca:<slug>" for a ComplyAdvantage monitoring hit.
subjectIdstring | nullThe screened subject id within the case roster (null for monitoring-sourced hits).
subjectNamestring | nullThe screened party (customer director/UBO/company), not the matched entity.
subjectRolestring | nulle.g. "director", "ubo", "company".
captionstring | nullThe matched watchlist entity name.
schemastring | nullMatch entity type, e.g. "Person" or "Company".
scorenumber | nullVendor match score.
topicsstring[]Topic/category tags (e.g. "sanction", "role.pep").
positionstring[]PEP positions held by the matched entity.
nationalitystring[]Nationalities of the matched entity.
isPepboolean—
isSanctionedboolean—
sourcestring"screening" or "comply_advantage_native".

Sample payload

{
  "event": "screening.hit.detected",
  "timestamp": "2026-05-14T09:25:40.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "hitId": "NK-12345",
  "subjectId": "subj-1",
  "subjectName": "Maria Lopez",
  "subjectRole": "director",
  "caption": "Maria LOPEZ",
  "schema": "Person",
  "score": 0.92,
  "topics": ["sanction.linked", "role.pep"],
  "position": ["Member of Parliament"],
  "nationality": ["ES"],
  "isPep": true,
  "isSanctioned": false,
  "source": "screening"
}
screening.hit.triagedEventSchema (v1) ↗

AI per-hit triage completed for an OpenSanctions hit or adverse-media article. The hitId is the raw OpenSanctions id, or "am:<id>" for adverse-media.

FieldTypeNotes
caseIdstring—
hitIdstringHit identifier — raw OpenSanctions id, or "am:<adverse_media_results.id>".
subjectNamestringSubject this hit is associated with.
statusstring"complete" or "failed".
confidencenumber0–100 AI confidence score.
dispositionstring"false_positive", "true_match", or "escalate".
shortReasonstringOne-line analyst-facing rationale.
providerstringTriage engine — "claude" or "diligent".
modelstringAnthropic model used (e.g. "claude-opus-4-5").
promptVersionstringPrompt version, currently "1".

Sample payload

{
  "event": "screening.hit.triaged",
  "timestamp": "2026-05-14T09:25:48.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "hitId": "NK-12345",
  "subjectName": "Maria Lopez",
  "status": "complete",
  "confidence": 92,
  "disposition": "true_match",
  "shortReason": "Strong identity match with adverse-media context.",
  "provider": "claude",
  "model": "claude-opus-4-5",
  "promptVersion": "1"
}
screening.hit.escalatedEventSchema (v1) ↗

An analyst escalated a screening match, an adverse-media article or a self-exclusion match from the app, and the senior they picked was told. It carries no note: the analyst’s note to the senior stays in the app. A /v1 escalation doesn’t send it, because it names no senior.

FieldTypeNotes
caseIdstring—
hitIdstringThe escalated hit: the screening hit’s id, "am:<id>" for an adverse-media article, or the self-exclusion hit’s id.
matchstring"screening_hit", "adverse_media" or "self_exclusion".
escalatedBystring | nullThe analyst who escalated it.
escalatedTostringThe senior they picked, an MLRO, Compliance admin or Admin.
emailedbooleanWhether the email to the senior was sent. false when it couldn’t be, for example while their access is suspended.

Sample payload

{
  "event": "screening.hit.escalated",
  "timestamp": "2026-05-14T09:31:02.540Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "hitId": "NK-12345",
  "match": "screening_hit",
  "escalatedBy": "analyst@demobank.example",
  "escalatedTo": "mlro@demobank.example",
  "emailed": true
}
person.linkedEvent

An analyst linked a case-side subject to a tenant Person row (Cross-Case Identity Linking, Task #79).

FieldTypeNotes
caseIdstring—
personIdnumberpersons.id of the canonical Person row.
personKeystringThe case-side personKey that was linked.
displayNamestring—
emailstring | null—
rolesstring[]Roles this subject holds on the case.
linkedBystringAnalyst email.

Sample payload

{
  "event": "person.linked",
  "timestamp": "2026-05-14T09:24:01.221Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "personId": 7001,
  "personKey": "00000000-0000-0000-0000-000000000001",
  "displayName": "Jane Smith",
  "email": "jane.smith@example.com",
  "roles": ["director"],
  "linkedBy": "alex.kim@demobank.com"
}
person.unlinkedEvent

An analyst removed an active case-to-Person link (soft-delete via unlinked_at).

FieldTypeNotes
caseIdstring—
personIdnumber—
personKeystring—
unlinkedBystringAnalyst email.
reasonstring | nullOptional analyst reason.

Sample payload

{
  "event": "person.unlinked",
  "timestamp": "2026-05-14T09:25:00.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "personId": 7001,
  "personKey": "00000000-0000-0000-0000-000000000001",
  "unlinkedBy": "alex.kim@demobank.com",
  "reason": "Wrong individual on initial link."
}
person.marked_newEvent

An analyst confirmed "no prior match" for a subject — a new Person row was created and linked.

FieldTypeNotes
caseIdstring—
personIdnumbernewly-created persons.id.
personKeystring—
displayNamestring—
emailstring | null—
resolvedBystringAnalyst email.

Sample payload

{
  "event": "person.marked_new",
  "timestamp": "2026-05-14T09:24:55.221Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "personId": 7002,
  "personKey": "00000000-0000-0000-0000-000000000001",
  "displayName": "Jane Smith",
  "email": "jane.smith@example.com",
  "resolvedBy": "alex.kim@demobank.com"
}
person.document_attachedEvent

An analyst attached a Passport/ID document on a case to a Person profile so it is reusable on future cases within the tenant validity window.

FieldTypeNotes
caseIdstring—
personIdnumber—
documentIdnumber—
documentTypestringDocument type (typically "Passport" or "Government ID").
attachedBystringAnalyst email.

Sample payload

{
  "event": "person.document_attached",
  "timestamp": "2026-05-14T09:26:11.880Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "personId": 7001,
  "documentId": 4713,
  "documentType": "Passport",
  "attachedBy": "alex.kim@demobank.com"
}
outreach.email.sentEvent

A customer-facing outreach email was sent (e.g. document request) — one emit per send.

FieldTypeNotes
caseIdstring—
kindstringEmail kind, e.g. "document_request".
recipientEmailstring—
subjectstringEmail subject line.
itemCountnumber—
itemsarrayArray of {key, label} for each outstanding item included in the email.
sentBystringAnalyst email.

Sample payload

{
  "event": "outreach.email.sent",
  "timestamp": "2026-05-14T10:02:18.881Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "kind": "document_request",
  "recipientEmail": "ops@acmeholdings.example",
  "subject": "Additional documentation requested — Acme Holdings Ltd",
  "itemCount": 2,
  "items": [
    { "key": "register_of_directors", "label": "Register of Directors" },
    { "key": "proof_of_address",      "label": "Proof of Address — UBO Maria Lopez" }
  ],
  "sentBy": "alex.kim@demobank.com"
}
escalation.createdEvent

A case was escalated for senior review: by an analyst, or by the system when monitoring confirmed a match that moved the risk band, or when the band rose during a periodic review (companion to case.status.changed).

FieldTypeNotes
caseIdstring—
companyNamestring | nullAn analyst's escalation only.
notestringAn analyst's note, or monitoring's. Never sent for a periodic review's.
raisedBystringAnalyst email, on an analyst's escalation.
escalationIdnumberThe system's escalations.
assigneestring | nullThe MLRO it went to, on the system's; null when nobody is nominated and every MLRO was told.
source'monitoring_review' | 'periodic_review'The system's escalations: what raised it.
reasonstringThe system's: 'band_increase', and for monitoring also 'analyst_escalate' or 'model_drift'.

Sample payload

{
  "event": "escalation.created",
  "timestamp": "2026-05-14T10:42:18.221Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "note": "Senior review requested — high-risk jurisdiction with PEP-linked UBO.",
  "raisedBy": "alex.kim@demobank.com"
}
escalation.respondedEvent

A senior reviewer responded to an escalation with approve/decline/refer (companion to case.status.changed; carries the senior note + recommendation).

FieldTypeNotes
caseIdstring—
companyNamestring | null—
recommendationstring"approve", "decline", or "refer".
notestringSenior reviewer note.
respondedBystringSenior reviewer email.

Sample payload

{
  "event": "escalation.responded",
  "timestamp": "2026-05-14T10:55:01.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "recommendation": "approve",
  "note": "Approved on review — EDD complete, PEP adjudicated as cleared.",
  "respondedBy": "senior-manager@demobank.com"
}
owner.changedEvent

A case owner was assigned, reassigned, or cleared (case-row branch only — form-draft owner changes do not fire).

FieldTypeNotes
caseIdstring—
previousOwnerobject | nullPrevious owner {name, email}, or null if previously unassigned.
newOwnerobject | nullNew owner {name, email}, or null on unassign.
changedBystring | nullAnalyst email of the actor.
reasonstringPresent only when the platform cleared the owner itself: "member_removed" when the owner was removed from your organisation. changedBy is then the admin who removed them.

Sample payload

{
  "event": "owner.changed",
  "timestamp": "2026-05-14T09:23:11.005Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "previousOwner": null,
  "newOwner": { "name": "Alex Kim", "email": "alex.kim@demobank.com" },
  "changedBy": "alex.kim@demobank.com"
}
case.onboarding_progress.changedEventSchema (v1) ↗

The case meaningfully advanced through onboarding — a new journey stage was reached OR a director/UBO/signatory’s verification status changed. De-duplicated: it fires only on a real change, never on a no-op recompute. Ideal for painting a live progress bar + per-contact checklist onto a CRM record.

FieldTypeNotes
caseIdstring—
companyNamestring | nullSubject company name (null for individual cases).
stagestringFurthest-along stage: created | invite_sent | collecting_documents | application_submitted | in_screening | awaiting_id_verification | decision_made.
stageLabelstringPlain-language label for stage.
summaryobject{ verified, total } headline count of the roster.
rosterarrayPer-person verification list. Each item: { name, role, status, statusLabel }. status is a coarse, customer-safe value (link_sent | in_progress | action_needed | verified) — never an internal IDV outcome, and the roster never carries email, person key, EDD, risk or screening-adjudication data.
crmSourcestring | nullThe CRM the case originated from (e.g. "salesforce").

Sample payload

{
  "event": "case.onboarding_progress.changed",
  "timestamp": "2026-05-14T09:25:42.118Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "companyName": "Acme Holdings Ltd",
  "stage": "awaiting_id_verification",
  "stageLabel": "Awaiting identity verification",
  "summary": { "verified": 1, "total": 2 },
  "roster": [
    { "name": "Jane Smith", "role": "Director", "status": "verified", "statusLabel": "Verified" },
    { "name": "John Doe", "role": "Beneficial Owner", "status": "in_progress", "statusLabel": "In progress" }
  ]
}
case.data_package.deliveredEventSchema (v1) ↗

A case decision is recorded AND the tenant has opted into full-parity egress (double-gated: FML-unlocked entitlement + compliance-admin toggle, OFF by default). Emitted once at decision time. Carries the COMPLETE record FML holds — company profile, full ownership roster with ownership %/nationality/DOB, every extracted document field, and the decision/risk/screening summary. This is the deliberate opposite of case.onboarding_progress.changed (which strips all PII). Its successful (2xx) delivery is also the Zero-Retention purge precondition for full-parity tenants.

FieldTypeNotes
caseIdstring—
decidedAtstringThe decision timestamp this package corresponds to. Stable across redelivery; the Zero-Retention gate correlates 2xx delivery to this exact decision.
outcomestring | nullThe decision outcome at package time (e.g. "approved", "declined").
crmRecordIdstring | nullCRM record id echoed back for correlation.
crmSourcestring | nullThe CRM the case originated from (e.g. "salesforce").
fullParityobjectThe complete case projection: { caseId, orgId, status, companyProfile, ownership: { directors, ubos }, documents (with full extractedData), decision, risk, screeningSummary }. Same shape as the fullParity slice attached to lifecycle webhooks and the Pull API case detail when full-parity egress is enabled. Each owner carries name, email, roles, ownershipPercent, nationality, dateOfBirth, idNumber, idCountry, countryOfResidence.

Sample payload

{
  "event": "case.data_package.delivered",
  "timestamp": "2026-05-14T11:04:09.220Z",
  "orgId": "org_demo_bank",
  "crmRecordId": "0035g00000Abc12AAA",
  "crmSource": "salesforce",
  "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
  "decidedAt": "2026-05-14T11:04:08.901Z",
  "outcome": "approved",
  "fullParity": {
    "caseId": "8a0e8d9c-7b1a-4f2e-9c3b-2d1e8f7a4b6c",
    "orgId": "org_demo_bank",
    "status": "approved",
    "crmRecordId": "0035g00000Abc12AAA",
    "crmSource": "salesforce",
    "companyProfile": {
      "companyName": "Acme Holdings Ltd",
      "registrationNumber": "12345678",
      "country": "GB",
      "entityType": "Private limited company",
      "incorporationDate": "2015-04-01",
      "registeredAddress": "10 High Street, London, EC1A 1BB, GB",
      "taxId": "GB123456789",
      "vatNumber": "GB123456789",
      "businessActivity": "Investment holding",
      "industrySector": "Financial services",
      "annualRevenue": "£5m–£10m",
      "website": "https://acmeholdings.example",
      "customerEmail": "ops@acmeholdings.example",
      "sourceOfFunds": "Retained earnings",
      "transactsInternationally": true,
      "internationalCountries": ["US", "DE"],
      "customAnswers": {}
    },
    "ownership": {
      "directors": [
        { "name": "Jane Smith", "email": "jane.smith@acmeholdings.example", "roles": ["director"], "ownershipPercent": null, "nationality": "GB", "dateOfBirth": "1980-06-15", "idNumber": "123456789", "idCountry": "GB", "countryOfResidence": "GB", "source": "application_form" }
      ],
      "ubos": [
        { "name": "John Doe", "email": "john.doe@acmeholdings.example", "roles": ["ubo"], "ownershipPercent": 60, "nationality": "GB", "dateOfBirth": "1975-02-20", "idNumber": "987654321", "idCountry": "GB", "countryOfResidence": "GB", "source": "application_form" }
      ]
    },
    "documents": [
      { "id": 9001, "documentType": "Certificate of Incorporation", "filename": "certificate-of-incorporation.pdf", "mimeType": "application/pdf", "sizeBytes": 102400, "status": "complete", "confidence": "High", "uploadedAt": "2026-05-14T09:20:00.000Z", "warnings": [], "notes": null, "extractedData": { "companyName": "Acme Holdings Ltd", "registrationNumber": "12345678", "incorporationDate": "2015-04-01" } }
    ],
    "decision": { "outcome": "approved", "notes": "All documentation verified. UBO IDV passed.", "analystEmail": "alex.kim@demobank.com", "decidedAt": "2026-05-14T11:04:08.901Z" },
    "risk": { "compositeScore": 27, "band": "Low", "assessedAt": "2026-05-14T10:55:00.000Z" },
    "screeningSummary": { "totalHits": 0, "sanctionedHits": 0, "pepHits": 0 }
  }
}

4. Verify the signature

Signature verification is mandatory in production. Without it, anyone who learns your URL can forge a payload. The check is four steps:

  1. Read the X-FML-Signature header. Reject the request if it is missing or does not start with sha256=.
  2. Compute HMAC-SHA256(rawBody, sharedSecret) and hex-encode it.
  3. Constant-time compare "sha256=" + hex against the header. If it does not match, return 401.
  4. Replay window: reject the request if now - X-FML-Timestamp > 5 minutes. We send that header no more than 4 minutes old, so a window of 5 minutes or longer accepts every retry and every Redeliver. Use the header, not the body's timestamp: that is the time of the event, so it refuses our later retries and a late Redeliver.

Only the body is signed. The window turns away stale requests, but it can't stop a deliberate replay, because anyone holding a captured request can change X-FML-Timestamp. What stops a replay is deduplicating on the eventId in the body, as the receivers in section 6 do.

CriticalVerify against the raw request bytes, not the parsed object. JSON serialisers reorder keys and renormalise whitespace, which will break the HMAC. In Express, use express.raw(); in Flask, use request.data(not request.get_json()) for the HMAC step.

5. Salesforce — full worked example

The recommended Salesforce pattern is an Apex REST resource that verifies the HMAC, then enqueues a Queueable to do the CRM updates asynchronously. This keeps you well inside the 10-second response budget.

5.1 Salesforce-side prep

  1. Create a Custom Setting called FmlWebhookConfig__c with a single text field Secret__c. Paste the secret you got from First Mile Labs into the org-default record.
  2. Add custom fields on Account: FML_Case_Id__c (text, external ID, unique), FML_Status__c (text), FML_Customer_Email__c (email), FML_Decision_At__c (datetime).
  3. Make the Apex REST resource public via a Site or Connected App. The endpoint must be reachable without a Salesforce session, since First Mile Labs authenticates by HMAC, not OAuth.

5.2 Receiver class

// Salesforce Apex REST endpoint that accepts First Mile Labs webhooks.
// Path will be: https://your-instance.my.salesforce.com/services/apexrest/fml/webhook
@RestResource(urlMapping='/fml/webhook')
global with sharing class FmlWebhookReceiver {

    // Stored in Custom Settings or Named Credentials, never hard-coded.
    private static final String FML_SECRET =
        FmlWebhookConfig__c.getInstance().Secret__c;

    @HttpPost
    global static void receive() {
        RestRequest  req = RestContext.request;
        RestResponse res = RestContext.response;

        // 1. Signature header is mandatory.
        String sigHeader = req.headers.get('X-FML-Signature');
        String eventType = req.headers.get('X-FML-Event');
        String body      = req.requestBody.toString();

        if (String.isBlank(sigHeader) || !sigHeader.startsWith('sha256=')) {
            res.statusCode = 401; return;
        }

        // 2. Compute HMAC-SHA256 over the raw body and constant-time compare.
        Blob mac = Crypto.generateMac(
            'HmacSHA256',
            Blob.valueOf(body),
            Blob.valueOf(FML_SECRET)
        );
        String expected = 'sha256=' + EncodingUtil.convertToHex(mac);
        if (!constantTimeEquals(expected, sigHeader)) {
            res.statusCode = 401; return;
        }

        // 3. Acknowledge fast — heavy work goes to a queueable job.
        Map<String,Object> payload = (Map<String,Object>) JSON.deserializeUntyped(body);
        System.enqueueJob(new FmlWebhookProcessor(eventType, payload));

        res.statusCode = 200;
        res.responseBody = Blob.valueOf('{"ok":true}');
    }

    private static Boolean constantTimeEquals(String a, String b) {
        if (a.length() != b.length()) return false;
        Integer diff = 0;
        for (Integer i = 0; i < a.length(); i++) {
            diff |= a.charAt(i) ^ b.charAt(i);
        }
        return diff == 0;
    }
}

5.3 Queueable processor

// Queueable that maps a First Mile Labs event into Salesforce CRM objects.
public class FmlWebhookProcessor implements Queueable {
    private final String eventType;
    private final Map<String,Object> payload;

    public FmlWebhookProcessor(String eventType, Map<String,Object> payload) {
        this.eventType = eventType;
        this.payload   = payload;
    }

    public void execute(QueueableContext ctx) {
        String caseId       = (String) payload.get('caseId');
        String crmRecordId  = (String) payload.get('crmRecordId');

        // crmRecordId is the Salesforce Account / Opportunity ID you sent when
        // you created the FML case with POST /v1/cases. If present we update in
        // place; if null (a case opened another way) we create a new record,
        // and find it again on later events by FML_Case_Id__c.
        if (eventType == 'case.created') {
            Account a = (crmRecordId != null)
                ? new Account(Id = crmRecordId)
                : new Account(Name = (String) payload.get('companyName'));
            a.FML_Case_Id__c       = caseId;
            a.FML_Status__c        = 'in_progress';
            a.FML_Customer_Email__c = (String) payload.get('customerEmail');
            upsert a;
        } else if (eventType == 'case.decision.made') {
            Account a = [SELECT Id FROM Account WHERE FML_Case_Id__c = :caseId LIMIT 1];
            a.FML_Status__c    = (String) payload.get('outcome');
            a.FML_Decision_At__c = (Datetime) JSON.deserialize(
                '"' + payload.get('decidedAt') + '"', Datetime.class
            );
            update a;
        }
        // Add branches for case.status.changed, screening.completed, etc.
    }
}

5.4 Where crmRecordId comes from

crmRecordId is the id you send when Salesforce creates the case with POST /v1/cases (see the Salesforce integration guide). Every webhook for that case then arrives with it — no lookup needed. The API has no call that sets it after the case is created.

A case opened another way (by an analyst, or by the customer) has crmRecordId: null. Match those on caseId, which the processor above stores in FML_Case_Id__c. An analyst can also paste a record id into the case's CRM link panel, and later webhooks for that case carry it.

6. HubSpot, Zapier, and any other system

First Mile Labs does not ship CRM-specific connectors. Anything that can host an HTTPS endpoint and verify an HMAC works the same way as the Salesforce example above.

  • HubSpot: point the webhook at a Workflow webhook action via a small intermediary (Cloud Function, AWS Lambda, etc.) that verifies the HMAC and forwards the validated payload into HubSpot's API. HubSpot workflows themselves cannot verify HMAC signatures.
  • Zapier: use a Catch Raw Hook trigger so you receive the unparsed body, then verify the signature in a Code step before mapping fields into a Zap. The default Catch Hook trigger reformats the body and breaks the HMAC.
  • Custom service: drop in either of the receivers below.

Node / Express

// Generic Express receiver — drop in for any Node service.
import express from 'express';
import { createHmac, timingSafeEqual } from 'crypto';

const app = express();
const SECRET = process.env.FML_WEBHOOK_SECRET;
const REPLAY_WINDOW_MS = 5 * 60_000;            // 5 minutes
const seenEventIds = new Set();                 // swap for Redis in production

// IMPORTANT: capture the raw body BEFORE express.json() reformats it,
// otherwise the HMAC won't match (whitespace and key order matter).
app.post(
  '/webhooks/fml',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sigHeader = req.headers['x-fml-signature'] || '';
    if (!sigHeader.startsWith('sha256=')) return res.sendStatus(401);

    const expected = 'sha256=' + createHmac('sha256', SECRET)
      .update(req.body)
      .digest('hex');

    const a = Buffer.from(sigHeader);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }

    // Replay window — reject requests older than 5 minutes. Use this header:
    // the body's timestamp is the time of the event, so a late retry fails it.
    const ts = Date.parse(req.headers['x-fml-timestamp'] || '');
    if (!ts || Math.abs(Date.now() - ts) > REPLAY_WINDOW_MS) {
      return res.sendStatus(401);
    }

    const event   = req.headers['x-fml-event'];
    const payload = JSON.parse(req.body.toString('utf8'));

    // Idempotency — dedup on eventId (stable across retries). Read it from the
    // body, which is signed. The headers are not.
    if (payload.eventId && seenEventIds.has(payload.eventId)) return res.sendStatus(200);
    if (payload.eventId) seenEventIds.add(payload.eventId);

    // Acknowledge fast (under 10s) — defer heavy work to a queue.
    res.sendStatus(200);
    handleAsync(event, payload).catch(err =>
      console.error('webhook processing failed', err));
  }
);

Python / Flask

# Generic Flask receiver.
import hmac, hashlib, os
from datetime import datetime, timezone
from flask import Flask, request, abort

app    = Flask(__name__)
SECRET = os.environ['FML_WEBHOOK_SECRET'].encode()
REPLAY_WINDOW_S = 5 * 60          # 5 minutes
seen_event_ids  = set()           # swap for Redis in production

@app.post('/webhooks/fml')
def fml_webhook():
    sig_header = request.headers.get('X-FML-Signature', '')
    if not sig_header.startswith('sha256='):
        abort(401)
    expected = 'sha256=' + hmac.new(SECRET, request.data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig_header):
        abort(401)

    # Replay window. Use this header: the body's timestamp is the time of the
    # event, so a late retry fails it.
    ts_header = request.headers.get('X-FML-Timestamp', '')
    try:
        ts = datetime.fromisoformat(ts_header.replace('Z', '+00:00'))
    except ValueError:
        abort(401)
    if abs((datetime.now(timezone.utc) - ts).total_seconds()) > REPLAY_WINDOW_S:
        abort(401)

    event   = request.headers.get('X-FML-Event')
    payload = request.get_json()

    # Idempotency on eventId (stable across retries). Read it from the body,
    # which is signed. The headers are not.
    event_id = payload.get('eventId')
    if event_id and event_id in seen_event_ids:
        return ('', 200)
    if event_id:
        seen_event_ids.add(event_id)

    # Ack fast, defer heavy work to a worker queue.
    return ('', 200)

7. Test the connection

There are four independent test paths, used at different points in the lifecycle:

7.1 Pre-save reachability ping

On the Add Endpoint form, click Send test ping before you save. This POSTs an event: "ping" payload to the URL you typed, signed with the secret you typed (or a freshly-generated one if blank). Use this to confirm DNS, TLS, and your receiver are wired up before you commit a misconfigured endpoint.

The ping payload looks like:

{
  "event": "ping",
  "eventId": "0d4e6b3c-9e4f-4a4a-b3a1-3f6f8c9b1a22",
  "eventVersion": 1,
  "timestamp": "2026-05-14T09:18:42.117Z",
  "orgId": "org_demo_bank",
  "message": "This is a test ping from First Mile Labs webhook infrastructure."
}

7.2 Post-save endpoint test

On any saved endpoint, click the Test button. This sends the same ping payload, but signed with the real stored secret— so it also proves your receiver is verifying signatures correctly. The result (HTTP status and first 500 bytes of the response body) appears next to the button.

7.3 Send a sample event

On a saved endpoint, choose an event type beside Send sample and click Send sample event. This sends a made-up instance of that event to that endpoint only, through the real delivery pipeline: signed with the stored secret, retried on the usual schedule, and listed in the Delivery Log. Its body carries "sample": true and placeholder values (the case id is CS-SAMPLE-0001, not a UUID), so your receiver can tell it from a real event. The list offers the event types ticked on the endpoint (an endpoint with none ticked shows no sample control), and the endpoint has to be active.

7.4 End-to-end with a real event

The cleanest dry-run uses a real lifecycle event:

  1. In the analyst console, create a new test case (or open an existing one).
  2. Take an action that emits an event — e.g. add a document to fire document.uploaded, or approve the case to fire case.decision.made.
  3. Open Outbound Webhooks → Delivery Log. You will see the delivery row appear within a second, with HTTP status, attempt count, and an expandable view of the full payload and the response body your receiver returned.
  4. Filter by endpoint to isolate just that receiver's traffic.

8. Retries & manual redelivery

Any non-2xx response, network error, or response that takes longer than 10 seconds is treated as a failed delivery. Failed deliveries are retried five times on a fixed schedule:

  • 1 second after the initial failure
  • 5 seconds
  • 30 seconds
  • 5 minutes
  • 30 minutes

Each wait runs from the previous attempt, and our retry job runs once a minute, so a retry goes out on the first run after its wait is up. In practice the five retries land about 1, 2, 3, 9 and 39 minutes after the event.

After the fifth retry the delivery is marked failed and no further automatic attempts are made. Every attempt — including the response body — is recorded in the delivery history for audit, and you can press Redeliver in the dashboard at any time to trigger a manual replay using the original payload.

The body stays the original on every attempt, timestamp included. A request sent more than 4 minutes after the event carries the time of sending in X-FML-Timestamp, so a 5-minute replay window accepts our late retries and Redeliver.

Pausing an endpoint in the dashboard stops delivery to it. Events that happen while it is paused are not queued, and a retry that falls due while it is paused is cancelled. Activating the endpoint again does not replay them: press Redeliver on each one you need.

Deactivating a workspace stops delivery the same way. Events that happen while it is deactivated are not queued, and a retry that falls due is cancelled. Reactivating the workspace does not replay them: press Redeliver on each one you need.

IdempotencyBecause of automatic retries and manual redelivery, your receiver must be idempotent. The supplied dedup key is eventId in the signed body (also sent as X-FML-Event-Id) — it is generated once when the event is emitted and stays the same across every retry and every manual replay of the same delivery row. Store seen event ids and short-circuit duplicates with a 200 OK.

Status codes and how we react:

Receiver returnsWe treat it asThen
2xx within 10 sDeliveredMark the delivery delivered. No further attempts.
4xx (any)FailureRetry on the schedule above. We do not short-circuit 4xx — receivers occasionally return 401 during a secret rotation and recover on the next attempt.
5xx (any)FailureRetry on the schedule above.
No response in 10 sFailure (timeout)Retry on the schedule above. Logged with HTTP 0.
Network error / DNS failureFailureRetry on the schedule above. Logged with HTTP 0 and the underlying error message.

9. Using with an iPaaS (Workato, MuleSoft, Boomi, Tray)

The contract above is designed to work cleanly with mainstream integration platforms. There is no FML-specific connector to install — point an iPaaS HTTP trigger at your endpoint URL, configure HMAC verification with your shared secret, and you are done.

  • Trigger type: use the platform's HTTP / Webhook trigger that exposes the raw request body and the full set of HTTP headers. Triggers that auto-parse JSON before you can hash it (e.g. Zapier's default Catch Hook, Workato's older HTTP webhook trigger) will break the HMAC — pick the raw variant.
  • Secret storage: store the shared secret in the platform's secret manager (Workato connection vault, MuleSoft Secure Configuration Properties, Boomi Vault) — never in plain recipe / process state.
  • Idempotency: deduplicate on eventId from the signed body (X-FML-Event-Id carries the same value). Most platforms have a built-in "remember last N keys" or persistent recipe-state primitive — use it.
  • Replay window: enforce now - X-FML-Timestamp ≤ 5 minutes as the first step in your recipe. Use this header, not the body's timestamp, which stays at the time of the event on every retry.
  • Versioning: branch recipes on X-FML-Event-Version. Today it is 1; if it ever becomes 2, your 1 branch keeps running unchanged until you migrate.
  • Acknowledgement: respond 2xx within 10 s and run heavier downstream actions in an async recipe / queue. iPaaS platforms doing synchronous downstream calls inside the trigger will frequently breach the 10 s budget.
  • Failures: let our retry schedule handle transient errors — return 5xx when your downstream is unhealthy and we'll back off and retry. Manual re-runs are available from the analyst console under Outbound Webhooks → Delivery Log → Redeliver.

Compatibility policy

  • Additive changes (new event types, new fields on existing payloads, new headers) do not bump X-FML-Event-Version. Receivers that ignore unknown fields and headers will keep working.
  • Breaking changes (renames, removals, signature scheme changes) bump the version. We will email registered endpoint owners at least 60 days before a version bump and run both versions side-by-side during the transition window.
  • Event names are stable. An event such as case.approved retains its meaning forever; if we need a different shape we publish a new event name (e.g. case.approved.v2) rather than mutating the old one.

10. Troubleshooting

SymptomLikely cause & fix
Endpoint creation rejected: "Webhook URL must not target a private or loopback address."The URL resolves to a private, loopback, link-local, CGN, IPv6-local, or cloud-metadata address. SSRF protection blocks these. Use a public HTTPS URL or expose your service via a tunnel such as ngrok or Cloudflare Tunnel.
Test ping returns HTTP 0 with a network error.Receiver did not respond within 10 seconds, the TLS handshake failed, or DNS could not resolve. Verify the URL with curl -X POST from outside your network.
Receiver returns 401 on every delivery.HMAC mismatch. Almost always one of: (1) computing the HMAC over the parsed JSON instead of the raw bytes; (2) using the wrong secret (production vs. staging); (3) trimming or modifying the body before verification.
First attempts are accepted, but late retries and Redeliver get 401.Your replay window is reading the body's timestamp, which stays at the time of the event. Read X-FML-Timestamp instead: see section 4.
Deliveries are stuck on Pending retry.Your receiver is returning a non-2xx status. Open the delivery row to see the response body — that is exactly what your endpoint sent back. Once you fix the receiver, the next retry will succeed automatically (or click Redeliver to force it now).
A delivery reads Failed, with the response Retry cancelled: the endpoint is paused.The endpoint was paused while the delivery was waiting for a retry, so the retry was cancelled. Activate the endpoint, then click Redeliver.
A delivery reads Failed, with the response Retry cancelled: the workspace was deactivated.The workspace was deactivated while the delivery was waiting for a retry, so the retry was cancelled. Click Redeliver to send it again.
Receiver gets the same event twice.Either an automatic retry succeeded after a soft-failure, or someone clicked Redeliver. Make your handler idempotent — see the callout in section 8.
crmRecordId is always null.The cases were created without one. Send crmRecordId in the POST /v1/cases call that creates the case: nothing in the API sets it afterwards. For a case opened another way, match on caseId, or have an analyst paste the id into the case's CRM link panel.
You stop receiving events for one type but others still arrive.Someone unticked that event type when editing the endpoint. Open the endpoint in the dashboard and re-enable it.

Need help? If a specific delivery is failing in production, share the delivery ID from the Delivery Log with our support team and we can replay it from the audit trail. Contact us.