Notifications & Webhooks — FrankieOne

To set up webhooks, have your designated contact email help@frankieone.com. You can configure up to three separate endpoint collections for:

Background function notifications
Risk change events
Check process results

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).

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

1 {
2     "checkId": "11111111-2222-3333-4444-555555555555",
3     "entityId": "12345678-1234-1234-4321-123487650912",
4     "function": "UpdateCheckEntity",
5     "functionResult": "COMPLETED",
6     "notificationType": "EVENT",
7     "requestId": "01EKVV810DC7NJEC97BAQJZXWR"
8 }

Handling Notifications

Receive the Webhook

Your endpoint should respond with a 200 or 202 HTTP status code to acknowledge receipt.

Process the Notification Type

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

Retrieve Additional Data

For background operations, call 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)

We secure notification payloads through HTTPS and firewall IP whitelisting. You can also sign your requests with JSON Web Tokens to add an additional layer of security and verify message validity. Contact support to enable JWT verification for your account.

JWT Structure

Security Features

Retry Mechanism

When webhook delivery fails to more than half of the configured endpoints:

The system retries delivery every 15 minutes, with up to 50 retries.
If all 50 retries fail, the message moves to a Dead Letter Queue (DLQ) and notifies our support team

Webhook Notification Function Names

Webhook function	Reference/Definition
AssociatedEntityStatusChange	Used when there’s a change to an associated entity
BlacklistEntity	Set Entity Blacklist State
BusinessDocumentCatalogue	(International) List available documents in catalogue
BusinessOwnershipQuery	(AUS Only) Create Business Entity and Query UBO
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
CreateEntityGetIDVToken	Create Entity and Get IDV Token
CreateProcessIndustryUtilityDocument	Create Document and Run Utility Price Comparison
DeleteDocument	Delete Document
DeleteEntity	Delete Entity
DeleteEntityAssociation	(AUS Only) Remove a previously created association between an entity (otherId) and a parent organisation (entityId)
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
notifyResult	Push Notification Payload
OrderBusinessDocument	(International) Order document from catalogue
QueryDocument	Retrieve Document Details
QueryDocumentChecks	Retrieve Document Verification Check Details
QueryDocumentFull	Retrieve Document and Scan Data
QueryEntity	Retrieve Entity Details
QueryEntityChecks	https://apidocs.frankiefinancial.com/reference/queryentitychecks
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 against a new or existing organisation entity
RunBusinessReportsMulti	https://apidocs.frankiefinancial.com/reference/runbusinessreportsmulti
SearchDocument	Search For a Document [Beta]
StatusCheck	Service Status
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
UpdateEntityGetIDVToken	Update Entity and Get IDV Token
UpdateEntityInitIDVProcess	https://apidocs.frankiefinancial.com/reference/updateentityinitidvprocess
UpdateEntityState	When you manually override the result of an entity in Portal, the entity status will change, and this notification will be sent to your webhook
UpdateEvaluateEntity	Update Entity and evaluate current results and risk without running any new checks
UpdateProcessIndustryUtilityDocument	Update Document and Run Utility Price Comparison
UpdateProcessIndustryUtilityDocumentConsent	Provide Explicit Consent to Switch Utility Plans
UpdateProcessIndustryUtilityDocumentSwitch	Initiate Switching of Utility Plan
UpdateTransactionCase	The notification is sent when a change in status/resolution for an Alert occurs - https://apidocs.frankiefinancial.com/reference/patchbulkresolvecases
UpdateVerifyDocument	Update and Verify Document
VerifyDocument	Create and Verify Document
WatchlistEntity	Set Entity Watchlist State

1	{
2	"checkId": "11111111-2222-3333-4444-555555555555",
3	"entityId": "12345678-1234-1234-4321-123487650912",
4	"function": "UpdateCheckEntity",
5	"functionResult": "COMPLETED",
6	"notificationType": "EVENT",
7	"requestId": "01EKVV810DC7NJEC97BAQJZXWR"
8	}