Notifications & Webhooks | FrankieOne

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

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

JWT Structure

1 {
2   "header": {
3     "alg": "RS256",
4     "typ": "JWT"
5   },
6   "body": {
7     "sub": "agent@email.com", // Portal notifications only
8     "iat": 1516239022,        // UTC epoch timestamp in seconds
9     "iss": "one.frankie.api"  // Fixed string
10   }
11 }

Security Features

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

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
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
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://docs.frankieone.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(s) against a new or existing organisation entity.
RunBusinessReportsMulti	https://docs.frankieone.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://docs.frankieone.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
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
IDVTokenRequested	When a token is requested for IDV verification
IDVResultsRetrieved	When IDV results are retrieved
IDVOCRProcessing	When IDV OCR processing is completed
OnbTokenRequested	When a token is requested for onboarding
WorkflowComplete	When a workflow execution is completed