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.
- 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.
- 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.
- 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
2xxwithin 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.
- Click Add Endpoint. A form appears with URL, label, secret, and event-type fields.
- 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. - Add a label. Free text such as "Salesforce — production". Used in the dashboard and delivery list.
- 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.
- 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. - (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. - Click Add Endpoint at the foot of the form. The endpoint is now active.
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 theX-FML-Event-Idheader).eventVersion— integer contract version, currently1. 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: useX-FML-Timestamp(see section 4).orgId— your First Mile Labs organisation identifier.crmRecordId— present whenevercaseIdis present. Echoes back thecrmRecordIdyour CRM sent when it created the case withPOST /v1/cases, so you can update the right record without a lookup.nullif 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/jsonX-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 ofeventIdin 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 astimestampin 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.1on the initial try,2on 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:
.v1.json); a future eventVersion bump will ship a .v2.json alongside without breaking consumers.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.A new case is opened — manual analyst creation, customer doc upload, application form submission, or POST /v1/cases.
| Field | Type | Notes |
|---|---|---|
caseId | string | First Mile Labs case identifier, a UUID. |
companyName | string | null | Subject company name when known. |
companyNumber | string | null | Registry number when collected (e.g. Companies House number). |
country | string | null | ISO country / jurisdiction of the subject company. |
customerEmail | string | null | Email of the customer the case belongs to. |
source | string | One of "manual", "doc_upload", "application_form", or "api" for a case created through POST /v1/cases. |
createdBy | string | Analyst 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"
}The customer has finished their part — application form submitted or customer review confirmed.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
companyName | string | null | — |
country | string | null | — |
customerEmail | string | null | — |
source | string | "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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
outcome | string | "approved" or "declined". |
notes | string | Free-text decision notes captured in the analyst panel, or why the platform decided. |
analystEmail | string | Analyst who made the decision, or "policy_engine" for an automatic decision. |
decidedAt | string (ISO 8601) | Decision timestamp. |
companyName | string | null | — |
auto | boolean | true on an automatic decision; absent on an analyst's. |
reason | string | Only 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"
}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).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
companyName | string | null | Absent on an exit’s change. |
status | string | New status (e.g. "approved", "declined", "pending_senior", "returned", "exited"). |
previousStatus | string | Status before the transition. |
changedBy | string | null | Email of the actor (analyst or customer), or "policy_engine" for an automatic decision. Null on an exit’s change, which names nobody. |
recommendation | string | Senior reviewer recommendation — only on returns from senior review. |
exitId | string (UUID) | Only on an exit’s change: the exit, as in the case.exit.* events. |
ledBy | string | Only 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"
}A customer corrected extracted data during review, or an analyst manually overrode an errored document (approve / escalate).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
source | string | "customer_review" or "analyst_override". |
amendmentCount | number | Customer review only — number of fields the customer changed. |
amendments | array | Customer review only — array of {section, field, originalValue, correctedValue} entries. |
documentId | number | Analyst override only — the document that was overridden. |
field | string | Analyst override only — always "document_status". |
originalValue | string | Analyst override only — typically "error". |
correctedValue | string | Analyst override only — "approved" or "escalated". |
note | string | Manual approval note. |
reason | string | Escalation reason. |
by | string | Analyst 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"
}
]
}One or more documents were uploaded to a case (single emit per upload batch).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
documentIds | number[] | Internal IDs of every uploaded document. |
fileCount | number | Number of files in the batch. |
filenames | string[] | 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"
]
}A sanctions / PEP / adverse media screening run finished for a case.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
screened | number | Total subjects screened (company plus directors and shareholders). |
summary | array | Array of {name, role, status} — status is "clear", "match", "pep", or "sanctioned". |
timestamp | string (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" }
]
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
reviewId | number | Internal id of the case_ai_reviews row. |
companyName | string | null | — |
triggeredBy | string | Analyst 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. |
recommendation | string | AI recommendation — one of "Approve", "Refer", or "Decline". |
confidence | string | Model confidence in the recommendation — one of "High", "Medium", or "Low". |
riskFactorCount | number | Number of risk factors the AI surfaced. |
riskFactors | array | Array of {text, severity} where severity is "HIGH", "MEDIUM", or "LOW". |
completedAt | string (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.processedEventA single uploaded document finished AI extraction successfully (one emit per document, complement of the batch document.uploaded).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
documentId | number | Internal id of the documents row. |
documentType | string | AI-classified document type, e.g. "Certificate of Incorporation". |
filename | string | Original filename as uploaded. |
status | string | Always "complete" — error completions do not fire this event. |
confidence | string | "High", "Medium", or "Low". |
warningCount | number | Number of AI warnings on the extraction. |
missingFieldCount | number | Number 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.assessedEventThe risk-scoring engine produced (or refreshed) a composite score for a case.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
assessmentId | number | Internal id of the risk_assessments row. |
configId | number | Active risk_model_config row this score was computed against. |
compositeScore | number | 0–100 composite score. |
bandId | string | Risk band — "low", "medium", "high", "prohibited". An approved override's band while one is in force. |
bandLabel | string | Human-readable band label. |
computedBandId | string | null | The band the engine computed, when an approved override replaced it; else null. |
computedBandLabel | string | null | Its label. |
riskOverrideId | string | null | The approved override in force, if any. |
cause | string | null | What 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. |
causedBy | string | null | Who did it. |
modelVersion | number | null | The 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. |
modelVersionMadeLiveBy | string | null | Who made that version live. |
modelVersionReason | string | null | The reason given when that version was a change made by hand; else null. |
assessedBy | string | "system" for automatic runs, analyst email for manual recompute. |
assessedAt | string (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.evaluatedEventA decision-policy run completed for a case (every time the rule engine evaluates the active policy).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
policyId | number | Active decision_policies row id. |
policyName | string | Human-readable name of the policy that was matched. |
matchedRuleIndex | number | null | Zero-indexed rule that matched, or null if the default branch fired or a platform rule overrode the policy. |
overrideReason | string | null | Why a platform rule overrode the policy, for example a company whose registry check did not pass. Null otherwise; absent on an age-gate rejection. |
outcome | string | "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. |
evaluatedAt | string (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.changedEventAn analyst marked an Enhanced Due Diligence requirement outstanding/received/waived (or updated its note).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
reqKey | string | Stable key for the requirement (e.g. "source_of_funds"). |
label | string | Human-readable requirement label. |
status | string | "outstanding", "received", or "waived". |
previousStatus | string | null | Status before the change. |
note | string | Free-text analyst note. |
updatedBy | string | Analyst 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.requestedEventAn EDD evidence-request email was sent to the customer (one emit per send).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
recipientEmail | string | — |
itemCount | number | — |
items | array | Array of {key, label} for each outstanding EDD item included in the email. |
sentBy | string | Analyst email. |
sentAt | string (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.dispatchedEventAn identity-verification (Didit) link was sent to a real person on the case (one emit per email — deduped by personKey across roles).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
recipientEmail | string | — |
recipientName | string | — |
personKey | string | Stable identity key (UUID v4) shared across the same real human within the case. |
roles | string[] | All roles this dispatch covers (e.g. ["director", "ubo"]). |
dispatchedBy | string | "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.completedEventA 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".
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
verificationType | string | The kind of check, for example "registry" or "identity". |
vendorName | string | The 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. |
position | number | The 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. |
role | string | The provider’s role in your set-up, "required" or "fallback". Not the person’s role on the case. |
outcome | string | What 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. |
errorMessage | string | null | Fixed text, "The check could not be completed.", when the check couldn’t be run. It never gives the reason. Null or absent otherwise. |
completedAt | string (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_documentEventA 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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
personName | string | — |
personEmail | string | null | — |
personKey | string | — |
roles | string[] | — |
satisfiedByDocId | number | Internal 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.createdEventA perpetual-monitoring run produced a new alert against an existing case.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
companyName | string | null | — |
runId | number | Internal id of the monitoring run that produced the alert. |
alertType | string | Alert category, e.g. "sanctions_hit" (a sanctions or PEP match), "structure_change" or "document_expiry". |
severity | string | "low", "medium", "high" or "critical". |
title | string | Short alert title. |
detail | string | Longer 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.completedEventA perpetual-monitoring run finished for a case (regardless of whether any alerts were generated).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
runId | number | — |
triggeredBy | string | "scheduled" or analyst email for ad-hoc runs. |
alertsGenerated | number | Number of new alerts produced by this run. |
checksRun | array | Array 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" }
]
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The monitored customer’s case — the record your CRM holds. Never the review case. |
reviewCaseId | string (UUID) | The review. Stable across every event for the same review. |
reviewRef | string | null | Human-readable review reference, e.g. "REV-2026-00012". |
alertType | string | The monitoring alert that opened the review, e.g. "sanctions_hit". |
severity | string | null | "low", "medium", "high" or "critical". |
subjectRole | string | null | The flagged party’s role, e.g. "UBO" or "Director". Never their name. |
subjectRef | string | null | Where the flagged party sits in the case’s ownership data, e.g. "ubo_0". |
personId | number | null | Person-registry id of the flagged party, when linked. |
occurrenceNo | number | 2 or more means this same fact has been reviewed on this customer before. |
state | string | Always "open". |
source | string | null | What raised the alert, e.g. "scheduled". |
priorDisposition | string | null | The 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
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The monitored customer’s case — the record your CRM holds. Never the review case. |
reviewCaseId | string (UUID) | The review. Stable across every event for the same review. |
reviewRef | string | null | Human-readable review reference, e.g. "REV-2026-00012". |
alertType | string | The monitoring alert that opened the review, e.g. "sanctions_hit". |
severity | string | null | "low", "medium", "high" or "critical". |
subjectRole | string | null | The flagged party’s role, e.g. "UBO" or "Director". Never their name. |
subjectRef | string | null | Where the flagged party sits in the case’s ownership data, e.g. "ubo_0". |
personId | number | null | Person-registry id of the flagged party, when linked. |
occurrenceNo | number | 2 or more means this same fact has been reviewed on this customer before. |
disposition | string | "true_match", "false_positive" or "escalate". |
dispositionBy | string | null | Analyst email. |
isReversal | boolean | True when this confirms a match a previous occurrence dismissed as a false positive. |
state | string | "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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The monitored customer’s case — the record your CRM holds. Never the review case. |
reviewCaseId | string (UUID) | The review. Stable across every event for the same review. |
reviewRef | string | null | Human-readable review reference, e.g. "REV-2026-00012". |
alertType | string | The monitoring alert that opened the review, e.g. "sanctions_hit". |
severity | string | null | "low", "medium", "high" or "critical". |
subjectRole | string | null | The flagged party’s role, e.g. "UBO" or "Director". Never their name. |
subjectRef | string | null | Where the flagged party sits in the case’s ownership data, e.g. "ubo_0". |
personId | number | null | Person-registry id of the flagged party, when linked. |
occurrenceNo | number | 2 or more means this same fact has been reviewed on this customer before. |
escalationReason | string | "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). |
escalationId | number | null | — |
assignedTo | string | null | The MLRO it was assigned to. Null when none is nominated and it waits in the senior queue. |
bandBefore | string | null | — |
bandAfter | string | 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"
}A second person approved the verdict and closed the review.
| Field | Type | Notes |
|---|---|---|
caseId | string | The monitored customer’s case — the record your CRM holds. Never the review case. |
reviewCaseId | string (UUID) | The review. Stable across every event for the same review. |
reviewRef | string | null | Human-readable review reference, e.g. "REV-2026-00012". |
alertType | string | The monitoring alert that opened the review, e.g. "sanctions_hit". |
severity | string | null | "low", "medium", "high" or "critical". |
subjectRole | string | null | The flagged party’s role, e.g. "UBO" or "Director". Never their name. |
subjectRef | string | null | Where the flagged party sits in the case’s ownership data, e.g. "ubo_0". |
personId | number | null | Person-registry id of the flagged party, when linked. |
occurrenceNo | number | 2 or more means this same fact has been reviewed on this customer before. |
disposition | string | "true_match", "false_positive" or "escalate". |
dispositionBy | string | null | Who reached the verdict. |
approvedBy | string | null | Who closed it — a different person while four-eyes is on. |
approvedAt | string (ISO 8601) | null | — |
bandBefore | string | null | The customer’s risk band before this review re-scored it, when it did. |
bandAfter | string | null | — |
bandReaffirmed | boolean | True 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
}A closed review was reopened. Its verdict and sign-off are cleared, so it needs a fresh decision and a fresh second person.
| Field | Type | Notes |
|---|---|---|
caseId | string | The monitored customer’s case — the record your CRM holds. Never the review case. |
reviewCaseId | string (UUID) | The review. Stable across every event for the same review. |
reviewRef | string | null | Human-readable review reference, e.g. "REV-2026-00012". |
alertType | string | The monitoring alert that opened the review, e.g. "sanctions_hit". |
severity | string | null | "low", "medium", "high" or "critical". |
subjectRole | string | null | The flagged party’s role, e.g. "UBO" or "Director". Never their name. |
subjectRef | string | null | Where the flagged party sits in the case’s ownership data, e.g. "ubo_0". |
personId | number | null | Person-registry id of the flagged party, when linked. |
occurrenceNo | number | 2 or more means this same fact has been reviewed on this customer before. |
reopenedBy | string | null | — |
previousDisposition | string | null | The 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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The customer’s case. |
exitId | string (UUID) | The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns. |
ledBy | string | "customer" (they asked to leave, or stopped trading) or "firm". |
endOn | string (YYYY-MM-DD) | The day the relationship ends. The record-keeping clock starts on it. |
state | string | Always "confirmed". |
confirmedAt | string (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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The customer’s case. |
exitId | string (UUID) | The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns. |
ledBy | string | "customer" (they asked to leave, or stopped trading) or "firm". |
endOn | string (YYYY-MM-DD) | The day the relationship ends. The record-keeping clock starts on it. |
state | string | Always "ended". |
endedAt | string (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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The customer’s case. |
exitId | string (UUID) | The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns. |
ledBy | string | "customer" (they asked to leave, or stopped trading) or "firm". |
endOn | string (YYYY-MM-DD) | The day the relationship ends. The record-keeping clock starts on it. |
state | string | Always "cancelled". |
cancelledAt | string (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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The customer’s case. |
exitId | string (UUID) | The exit. Stable across every event for the same exit, and what POST /v1/cases/{caseId}/exit returns. |
ledBy | string | "customer" (they asked to leave, or stopped trading) or "firm". |
endOn | string (YYYY-MM-DD) | The day the relationship ends. The record-keeping clock starts on it. |
state | string | Always "reversed". |
endedAt | string (ISO 8601) | null | When the exit had ended. |
reversedAt | string (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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The customer’s case. |
requestId | integer | The 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. |
itemCount | integer | — |
items | object[] | 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. |
delivery | string | "email": we emailed the customer. "link": the link went back to your API call, for you to send. |
source | string | "app", "api" or "automatic". |
joined | boolean | The items joined a request already open to the same person. |
addedCount | integer | How many items were new to the request. |
expiresAt | string (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": [] }
]
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | The customer’s case. |
requestId | integer | The 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. |
itemCount | integer | — |
items | object[] | 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. |
submittedAt | string (ISO 8601) | — |
uploadedCount | integer | Items with documents. |
declaredCount | integer | People’s Source of Wealth declared. |
answeredCount | integer | Items 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. |
pendingCount | integer | Items 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": [] }
]
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
hitId | string | Hit identifier — raw vendor id, or "ca:<slug>" for a ComplyAdvantage monitoring hit. |
subjectId | string | null | The screened subject id within the case roster (null for monitoring-sourced hits). |
subjectName | string | null | The screened party (customer director/UBO/company), not the matched entity. |
subjectRole | string | null | e.g. "director", "ubo", "company". |
caption | string | null | The matched watchlist entity name. |
schema | string | null | Match entity type, e.g. "Person" or "Company". |
score | number | null | Vendor match score. |
topics | string[] | Topic/category tags (e.g. "sanction", "role.pep"). |
position | string[] | PEP positions held by the matched entity. |
nationality | string[] | Nationalities of the matched entity. |
isPep | boolean | — |
isSanctioned | boolean | — |
source | string | "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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
hitId | string | Hit identifier — raw OpenSanctions id, or "am:<adverse_media_results.id>". |
subjectName | string | Subject this hit is associated with. |
status | string | "complete" or "failed". |
confidence | number | 0–100 AI confidence score. |
disposition | string | "false_positive", "true_match", or "escalate". |
shortReason | string | One-line analyst-facing rationale. |
provider | string | Triage engine — "claude" or "diligent". |
model | string | Anthropic model used (e.g. "claude-opus-4-5"). |
promptVersion | string | Prompt 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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
hitId | string | The escalated hit: the screening hit’s id, "am:<id>" for an adverse-media article, or the self-exclusion hit’s id. |
match | string | "screening_hit", "adverse_media" or "self_exclusion". |
escalatedBy | string | null | The analyst who escalated it. |
escalatedTo | string | The senior they picked, an MLRO, Compliance admin or Admin. |
emailed | boolean | Whether 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.linkedEventAn analyst linked a case-side subject to a tenant Person row (Cross-Case Identity Linking, Task #79).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
personId | number | persons.id of the canonical Person row. |
personKey | string | The case-side personKey that was linked. |
displayName | string | — |
email | string | null | — |
roles | string[] | Roles this subject holds on the case. |
linkedBy | string | Analyst 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.unlinkedEventAn analyst removed an active case-to-Person link (soft-delete via unlinked_at).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
personId | number | — |
personKey | string | — |
unlinkedBy | string | Analyst email. |
reason | string | null | Optional 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_newEventAn analyst confirmed "no prior match" for a subject — a new Person row was created and linked.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
personId | number | newly-created persons.id. |
personKey | string | — |
displayName | string | — |
email | string | null | — |
resolvedBy | string | Analyst 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_attachedEventAn 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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
personId | number | — |
documentId | number | — |
documentType | string | Document type (typically "Passport" or "Government ID"). |
attachedBy | string | Analyst 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.sentEventA customer-facing outreach email was sent (e.g. document request) — one emit per send.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
kind | string | Email kind, e.g. "document_request". |
recipientEmail | string | — |
subject | string | Email subject line. |
itemCount | number | — |
items | array | Array of {key, label} for each outstanding item included in the email. |
sentBy | string | Analyst 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.createdEventA 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).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
companyName | string | null | An analyst's escalation only. |
note | string | An analyst's note, or monitoring's. Never sent for a periodic review's. |
raisedBy | string | Analyst email, on an analyst's escalation. |
escalationId | number | The system's escalations. |
assignee | string | null | The 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. |
reason | string | The 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.respondedEventA senior reviewer responded to an escalation with approve/decline/refer (companion to case.status.changed; carries the senior note + recommendation).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
companyName | string | null | — |
recommendation | string | "approve", "decline", or "refer". |
note | string | Senior reviewer note. |
respondedBy | string | Senior 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.changedEventA case owner was assigned, reassigned, or cleared (case-row branch only — form-draft owner changes do not fire).
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
previousOwner | object | null | Previous owner {name, email}, or null if previously unassigned. |
newOwner | object | null | New owner {name, email}, or null on unassign. |
changedBy | string | null | Analyst email of the actor. |
reason | string | Present 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"
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
companyName | string | null | Subject company name (null for individual cases). |
stage | string | Furthest-along stage: created | invite_sent | collecting_documents | application_submitted | in_screening | awaiting_id_verification | decision_made. |
stageLabel | string | Plain-language label for stage. |
summary | object | { verified, total } headline count of the roster. |
roster | array | Per-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. |
crmSource | string | null | The 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" }
]
}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.
| Field | Type | Notes |
|---|---|---|
caseId | string | — |
decidedAt | string | The decision timestamp this package corresponds to. Stable across redelivery; the Zero-Retention gate correlates 2xx delivery to this exact decision. |
outcome | string | null | The decision outcome at package time (e.g. "approved", "declined"). |
crmRecordId | string | null | CRM record id echoed back for correlation. |
crmSource | string | null | The CRM the case originated from (e.g. "salesforce"). |
fullParity | object | The 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:
- Read the
X-FML-Signatureheader. Reject the request if it is missing or does not start withsha256=. - Compute
HMAC-SHA256(rawBody, sharedSecret)and hex-encode it. - Constant-time compare
"sha256=" + hexagainst the header. If it does not match, return401. - 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'stimestamp: 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.
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
- Create a Custom Setting called
FmlWebhookConfig__cwith a single text fieldSecret__c. Paste the secret you got from First Mile Labs into the org-default record. - 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). - 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:
- In the analyst console, create a new test case (or open an existing one).
- Take an action that emits an event — e.g. add a document to fire
document.uploaded, or approve the case to firecase.decision.made. - 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.
- 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.
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 returns | We treat it as | Then |
|---|---|---|
2xx within 10 s | Delivered | Mark the delivery delivered. No further attempts. |
4xx (any) | Failure | Retry 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) | Failure | Retry on the schedule above. |
| No response in 10 s | Failure (timeout) | Retry on the schedule above. Logged with HTTP 0. |
| Network error / DNS failure | Failure | Retry 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
eventIdfrom the signed body (X-FML-Event-Idcarries 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 minutesas the first step in your recipe. Use this header, not the body'stimestamp, which stays at the time of the event on every retry. - Versioning: branch recipes on
X-FML-Event-Version. Today it is1; if it ever becomes2, your1branch keeps running unchanged until you migrate. - Acknowledgement: respond
2xxwithin 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
5xxwhen 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.approvedretains 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
| Symptom | Likely 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.