Notifications & Webhooks

To set up webhooks, contact help@frankieone.com with your designated contact email. You can configure multiple webhook endpoints for different notification types. Ensure your endpoint is accessible via HTTPS.

Notification Triggers

Background Process Completion

Triggered when a background request (using X-Frankie-Background: 1 header) completes.

Entity State Changes

Triggered when an entity’s state changes (for example, UNCHECKED → PASS, FAIL → PASS).

Risk Level Changes

Triggered when an entity’s risk level changes (for example, LOW → HIGH, NULL → LOW).

IDV Biometrics Events

Triggered when an IDV biometrics event occurs (for example, token requested, results retrieved).

A single API request may trigger multiple notifications. For example, a background entity verification request could generate three webhooks: 1. Final risk score change 2. Final status change 3. Background process completion

Webhook Structure

Endpoint Format

FrankieOne appends the requestID to your configured webhook endpoint:

https://your-domain.com/webhook-endpoint/{requestID}

Payload Examples

{
    "checkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "documentId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "function": "EntityProfileChange",
    "functionResult": "COMPLETED",
    "notificationType": "EVENT",
    "message": "Profile changed from 'basic_kyc' to 'enhanced_kyc'",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "1.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "linkReference": "https://docs.frankieone.com/reference/retrieve"
}

{
    "checkId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "function": "EntityAssigneeChange",
    "functionResult": "COMPLETED",
    "notificationType": "EVENT",
    "message": "Entity was reassigned from 'analyst@company.com' to 'reviewer@company.com'",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "1.0.0",
    "entityCustomerReference": "customer-ref-12345"
}

{
    "checkId": "d4e5f6a7-b8c9-0123-def0-123456789012",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "function": "EntityStatusChange",
    "functionResult": "COMPLETED",
    "notificationType": "EVENT",
    "message": "Profile status changed from 'Needs Attention' to 'Passed'",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "1.0.0",
    "entityCustomerReference": "customer-ref-12345"
}

{
  "checkId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "entityId": "12345678-1234-1234-4321-123487650912",
  "function": "OCR_ERROR",
  "functionResult": "FAILED",
  "notificationType": "EVENT",
  "message": "Error encountered while processing OCR data.",
  "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
  "version": "1.0.0",
  "entityCustomerReference": "customer-ref-12345"
}

Payload Fields

Field	Type	Always Present	Description
`checkId`	string	No	Unique identifier (UUID) for the verification check that triggered the notification.
`documentId`	string	No	Unique identifier (UUID) of the document associated with the event.
`entityId`	string	Yes	Unique identifier (UUID) of the entity associated with the event.
`function`	string	Yes	The specific operation or event that triggered the notification. See Function Names Reference for a full list.
`functionResult`	string	Yes	The outcome of the function. Possible values: `COMPLETED`, `FAILED`.
`notificationType`	string	Yes	The category of the notification. Possible values: `FUNCTION`, `RESULT`, `EVENT`, `ALERT`. `EVENT` indicates a state or risk change; `FUNCTION` indicates a background process completion; `RESULT` indicates a result notification; `ALERT` indicates an alert notification.
`message`	string	Yes	A human-readable description of the event.
`requestId`	string	Yes	Unique identifier (ULID) for the original API request. Use this to retrieve results via the `/retrieve/{requestID}` endpoint.
`version`	string	Yes	The version of the webhook payload schema.
`entityCustomerReference`	string	No	Your custom reference identifier for the entity, as provided during entity creation.
`linkReference`	string	No	URI for resource containing more details about the reason for the notification.

Handling Notifications

Receive the Webhook

Your endpoint should respond with a 200 or 202 HTTP status code to acknowledge receipt. If your endpoint returns a 5xx or 4xx status code (other than 400), the system retries delivery multiple times over a period. A 400 status code stops retries.

Process the Notification Type

Use the notificationType and function fields to determine the appropriate action.

Retrieve Workflow Execution Results

Retrieve workflow execution results post-execution by calling the /retrieve endpoint with the provided requestID.

When can I `/retrieve` Data?

You can access cached API responses via the /retrieve/{requestID} endpoint for 7 days. You can retrieve RequestIDs in two cases:

Background/async calls that generate a FUNCTION webhook notification
Regular synchronous API calls with a response

Follow Up (if needed)

For state/risk changes, you may want to query additional information using:

GET /document/{id}/checks
GET /entity/{id}/checks

Additional Security (JWT Authentication)

FrankieOne supports JSON Web Token (JWT) authentication to enhance the security of webhook notifications. By enabling JWT signing, you can verify the authenticity and integrity of the payloads sent to your webhook endpoint.

Notification payloads are secured through HTTPS and IP whitelisting. You can also enable JSON Web Token (JWT) signing for additional security. Contact support to enable JWT verification for your account.

When JWT signing is enabled, FrankieOne includes the token in the Authorization header of the webhook HTTP POST request:

Authorization: Bearer <base64 header>.<base64 body>.<base64 signature>

The header and body are individually Base64 encoded and joined with a . separator. The signature is the Base64-encoded RSA-4096 encryption of the combined header and body. All three parts are concatenated to form the final JWT.

JWT Structure

{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "body": {
    "sub": "agent@email.com", // Portal notifications only
    "iat": 1516239022,        // UTC epoch timestamp in seconds
    "iss": "io.frankiefinancial.kycaml"  // Fixed string
  }
}

Security Features

RSA-4096 bit private key encryption
Customer-specific public key for verification
HTTPS with secure algorithms
IP whitelisting

Verifying the JWT

Extract the JWT from the Authorization: Bearer header.
Decode the Base64-encoded header and body.
Verify the signature using the public key provided by FrankieOne.
Validate the iss claim matches io.frankiefinancial.kycaml.
Validate the iat claim to ensure the token is not stale.

Retry Mechanism

FrankieOne employs a robust retry mechanism to ensure reliable delivery of webhook notifications:

Initial Retry: Immediately after the first failure.
Exponential Backoff: Retries occur at increasing intervals.
Maximum Retries: Up to 50 attempts over 24 hours.

If all retries fail, the message is moved to a Dead Letter Queue (DLQ), and FrankieOne’s support team is notified. Contact support to retrieve messages from the DLQ if necessary.

Webhook Notification Function Names

Function Names Reference Table

Webhook function	Reference/Definition
AssociatedEntityStatusChange	used when there’s a change to an associated entity
BlacklistEntity	Set Entity Blacklist State
BusinessOwnershipSubscription	(AUS Only) Subscribe or unsubscribe to continuous monitoring of business details and ownership.
CheckOrganisation	(AUS Only) Run KYC/AML Checks on Organisation and/or Associated Individuals.
CheckTransactionRisk	When asynchronous KYT transaction check has been sent, this notification is sent when the check has been successfully processed
CreateAssociateEntity	(AUS Only) Make a new entity a direct associated entity of a parent organisation.
CreateCheckEntity	Create and Verify Entity
CreateCheckEntityPushToMobile	Create Entity and Push Self-Verification Link
CreateDocument	Create New Document.
CreateEntity	Create New Entity.
DeleteDocument	Delete Document.
DeleteEntity	Delete Entity
DeleteEntityAssociation	(AUS Only) Remove a previously created association between an entity (otherId) and a parent organisation (entityId).
EntityAMLUpdate	When an AML update is received for an entity
EntityAssigneeChange	When an entity assignee changes
EntityMonitoring	Set Entity Ongoing AML Monitoring Status.
EntityProfileChange	When there’s a change to an entity profile recipe
EntityRiskChange	When an entity risk score changes
EntityStatusChange	When an entity overall status changes
FlagDuplicateEntity	Resolve Duplicate States
InternationalBusinessProfile	(International) Retrieve a business profile from any country.
InternationalBusinessSearch	(International) Search for a business from any country.
QueryDocument	Retrieve Document Details
QueryDocumentChecks	Retrieve Document Verification Check Details.
QueryDocumentFull	Retrieve Document and Scan Data
QueryEntity	Retrieve Entity Details
QueryEntityChecks	https://docs.frankieone.com/docs/v1/api/kyc-api-endpoints/reference/entity/query-entity
QueryEntityFull	Retrieve Entity Details and Document Scan Data
QueryOwnershipChecks	(AUS Only) Retrieve previous UBO query results
QueryParentAssociations	(AUS Only) Retrieve all the parent associations for an Individual or a Business
RetrieveResult	(Re)retrieve Response Result.
RunBusinessReports	(AUS Only) Run Report(s) against a new or existing organisation entity.
RunBusinessReportsMulti	https://docs.frankieone.com/reference/runbusinessreportsmulti
SearchDocument	Search For a Document [Beta]
UpdateAssociateEntity	(AUS Only) Make an existing entity (otherId) a directly associated entity of a parent organisation (entityId), or update an existing association.
UpdateCheckEntity	Update Entity and Verify Details
UpdateCheckEntityPushToMobile	Update Entity and Push Self-Verification Link
UpdateDocument	Update Existing Document
UpdateEntity	Update Existing Entity
UpdateEvaluateEntity	Update Entity and evaluate current results and risk without running any new checks
UpdateTransactionCase	The notification is sent when a change in status/resolution for an Alert occurs - https://docs.frankieone.com/reference/patchbulkresolvecases
UpdateVerifyDocument	Update and Verify Document
VerifyDocument	Create and Verify Document
WatchlistEntity	Set Entity Watchlist State
TOKEN_REQUESTED	When a token is requested for IDV verification
RESULTS_RETRIEVED	When IDV results are retrieved
OCR_PROCESSED	When IDV OCR processing is completed
ONB_URL_GENERATED	When an onboarding URL is generated

Guide to the API

KYC API Endpoints

Fraud & AML API Endpoints

IDV API Endpoints

KYB Trust Agent

KYB V2 API - Preview

Notifications & Webhooks

Notification Triggers

Background Process Completion

Entity State Changes

Risk Level Changes

IDV Biometrics Events

Webhook Structure

Endpoint Format

Payload Examples

Payload Fields

Handling Notifications

When can I `/retrieve` Data?

Additional Security (JWT Authentication)

Retry Mechanism

Webhook Notification Function Names

​Notification Triggers

Background Process Completion

Entity State Changes

Risk Level Changes

IDV Biometrics Events

​Webhook Structure

​Endpoint Format

​Payload Examples

​Payload Fields

​Handling Notifications

When can I /retrieve Data?

​Additional Security (JWT Authentication)

​Retry Mechanism

​Webhook Notification Function Names

Notification Triggers

Webhook Structure

Endpoint Format

Payload Examples

Payload Fields

Handling Notifications

When can I `/retrieve` Data?

Additional Security (JWT Authentication)

Retry Mechanism

Webhook Notification Function Names