Skip to main content
To set up webhooks, contact [email protected] 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": "01EKVV810DC7NJEC97BAQJZXWR",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "entityType": "INDIVIDUAL",
    "serviceName": "KYC",
    "function": "WorkflowComplete",
    "functionResult": "SUCCESS",
    "notificationType": "EVENT",
    "message": "Entity profile updated",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
    "version": "1.0.0",
    "entityCustomerReference": "customer-ref-12345",
    "overallStatus": "COMPLETED",
    "channel": "WEBHOOK"
}

​
Handling Notifications

1

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

Process the Notification Type

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

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:
  1. Background/async calls that generate a FUNCTION webhook notification
  2. Regular synchronous API calls with a response
4

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.
{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "body": {
    "sub": "[email protected]", // Portal notifications only
    "iat": 1516239022,        // UTC epoch timestamp in seconds
    "iss": "io.frankiefinancial.kycaml"  // Fixed string
  }
}
  • 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:
  1. Initial Retry: Immediately after the first failure.
  2. Exponential Backoff: Retries occur at increasing intervals.
  3. 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

Webhook functionReference/Definition
AssociatedEntityStatusChangeused when there’s a change to an associated entity
BlacklistEntitySet Entity Blacklist State
BusinessDocumentCatalogue(International) List available documents in catalogue
business.ownership.query(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.
CheckTransactionRiskWhen 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.
CreateCheckEntityCreate and Verify Entity
CreateCheckEntityPushToMobileCreate Entity and Push Self-Verification Link
CreateDocumentCreate New Document.
CreateEntityCreate New Entity.
CreateEntityGetIDVTokenCreate Entity and Get IDV Token
DeleteDocumentDelete Document.
DeleteEntityDelete Entity
DeleteEntityAssociation(AUS Only) Remove a previously created association between an entity (otherId) and a parent organisation (entityId).
EntityMonitoringSet Entity Ongoing AML Monitoring Status.
EntityProfileChangeWhen there’s a change to an entity profile recipe
EntityRiskChangeWhen an entity risk score changes
EntityStatusChangeWhen an entity overall status changes
FlagDuplicateEntityResolve Duplicate States
InternationalBusinessProfile(International) Retrieve a business profile from any country.
InternationalBusinessSearch(International) Search for a business from any country.
notifyResultPush Notification Payload
OrderBusinessDocument(International) Order document from catalogue
QueryDocumentRetrieve Document Details
QueryDocumentChecksRetrieve Document Verification Check Details.
QueryDocumentFullRetrieve Document and Scan Data
QueryEntityRetrieve Entity Details
QueryEntityCheckshttps://docs.frankieone.com/docs/v1/api/kyc-api-endpoints/reference/entity/query-entity
QueryEntityFullRetrieve 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.
RunBusinessReportsMultihttps://docs.frankieone.com/reference/runbusinessreportsmulti
SearchDocumentSearch For a Document [Beta]
StatusCheckService Status
UpdateAssociateEntity(AUS Only) Make an existing entity (otherId) a directly associated entity of a parent organisation (entityId), or update an existing association.
UpdateCheckEntityUpdate Entity and Verify Details
UpdateCheckEntityPushToMobileUpdate Entity and Push Self-Verification Link
UpdateDocumentUpdate Existing Document
UpdateEntityUpdate Existing Entity
UpdateEntityGetIDVTokenUpdate Entity and Get IDV Token
UpdateEntityInitIDVProcesshttps://docs.frankieone.com/reference/updateentityinitidvprocess
UpdateEntityStateWhen you manually override the result of an entity in Portal, the entity status will change, and this notification will be sent to your webhook.
UpdateEvaluateEntityUpdate Entity and evaluate current results and risk without running any new checks
UpdateTransactionCaseThe notification is sent when a change in status/resolution for an Alert occurs - https://docs.frankieone.com/reference/patchbulkresolvecases
UpdateVerifyDocumentUpdate and Verify Document
VerifyDocumentCreate and Verify Document
WatchlistEntitySet Entity Watchlist State
IDVTokenRequestedWhen a token is requested for IDV verification
IDVResultsRetrievedWhen IDV results are retrieved
IDVOCRProcessingWhen IDV OCR processing is completed
OnbTokenRequestedWhen a token is requested for onboarding
WorkflowCompleteWhen a workflow execution is completed