Event Notifications & Webhooks

FrankieOne uses webhooks to send real-time notifications about events in your system, such as a workflow completing or an entity’s risk profile changing. This allows you to build automated, event-driven integrations.

Setup

To configure webhook endpoints, contact support@frankieone.com with:

Your designated webhook endpoint URL(s)
Your contact email

You can configure multiple webhook endpoints for different notification types. Your endpoint must be accessible via HTTPS.

Webhook endpoints are configured by FrankieOne. There is no self-service API for webhook management.

Available Notifications

Workflow Events

Function	Description
`WorkflowComplete`	Sent when a workflow execution finishes, providing the final status and outcome. Also sent when there is an error during workflow execution — use the `functionResult` field to distinguish success from error.

IDV Biometrics Events

Function	Description
`TOKEN_REQUESTED`	Sent when a token is requested for IDV biometrics.
`ONB_URL_GENERATED`	Sent when an onboarding URL is successfully generated.
`RESULTS_RETRIEVED`	Sent when IDV biometrics results are successfully retrieved.
`OCR_PROCESSED`	Sent when OCR processing is completed.

These IDV function names are also sent when errors occur during the corresponding operation. Use the functionResult field to distinguish success from error.

Entity Profile Events

Function	Description
`EntityStatusChanged`	Sent when the overall status of an entity profile changes.
`EntityRiskChanged`	Sent when the risk level of an entity profile changes.
`EntityProfileUpdated`	Sent when an entity profile is updated.
`EntityAssigneeChanged`	Sent when the assignee of an entity profile changes.

Migrating from V1? Some webhook function names differ from their V1 counterparts and do not follow the same naming conventions. For example, V1’s EntityStatusChange is EntityStatusChanged in V2. Refer to the Migrating from V1 to see the key differences.

Webhook Payload

Payload Fields

Field	Type	Always Present	Description
`version`	string	Yes	The API version of the webhook payload.
`entityId`	string	Yes	The unique identifier of the entity related to the event.
`function`	string	Yes	The specific event that triggered the notification. See Available Notifications.
`functionResult`	string	Yes	The outcome of the event. `SUCCESS` indicates the operation completed successfully. `FAILURE` indicates the operation encountered an error or could not be completed.
`requestId`	string	Yes	The unique identifier of the API request that initiated the event.
`notificationType`	string	Yes	The category of notification. One of `FUNCTION`, `RESULT`, `EVENT`, `ALERT`.
`message`	string	Yes	A human-readable summary of the event.
`entityCustomerReference`	string	No	Your customer reference identifier, used for linking notifications to your internal records.
`workflowExecutionId`	string	No	The unique identifier of the workflow execution. Present when a workflow triggers the event.
`workflowName`	string	No	The name of the workflow that triggered the event.
`serviceName`	string	No	The name of the service profile involved.
`entityType`	string	No	The type of entity (e.g., `INDIVIDUAL`).
`overallRiskLevel`	string	No	The overall risk level of the entity. One of `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `UNACCEPTABLE`.
`overallStatus`	string	No	The overall status of the entity. One of `UNCHECKED`, `IN_PROGRESS`, `REVIEW`, `PASS`, `FAIL`, `COMPLETE`, `INCOMPLETE`, `NEEDS_APPROVAL`, `APPROVED`, `REJECTED`, `BLOCKED`, `CLEAR`, `URGENT`, `MONITOR`.
`channel`	string	No	The channel source from which the webhook was triggered. Present in v2 webhooks.
`assignee`	string	No	The assignee of the entity.
`customAttributes`	object	No	Custom attributes associated with the entity. Present in v2 webhooks when configured.

Event-Specific Fields

Depending on the function, additional fields may be present in the payload.

Function	Additional Fields	Description
`WorkflowComplete`	`workflowExecutionId`, `workflowName`, `overallStatus`	Identifiers and final status of the completed workflow.
`EntityStatusChanged`	`overallStatus`	The new overall status of the entity profile.
`EntityRiskChanged`	`overallRiskStatus`	The new risk level of the entity profile.

Endpoint Format

FrankieOne appends the requestID to your configured webhook endpoint:

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

Payload Examples

{
  "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
  "entityId": "12345678-1234-1234-4321-123487650912",
  "entityType": "INDIVIDUAL",
  "workflowName": "Onboarding",
  "serviceName": "KYC",
  "function": "WorkflowComplete",
  "functionResult": "SUCCESS",
  "notificationType": "EVENT",
  "message": "Entity profile updated",
  "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
  "version": "2.0.0",
  "entityCustomerReference": "customer-ref-12345",
  "overallStatus": "REVIEW",
  "channel": "api"
}

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.
A 400 response stops retries immediately.

2. Process the Notification

Use the notificationType and function fields to determine the appropriate action. Use functionResult to distinguish successful events from errors.

3. Retrieve Workflow Execution Results

After receiving a WorkflowComplete notification, retrieve the full workflow execution results by calling:

GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}

This endpoint is documented in the OpenAPI spec and available in the Postman collection. All path parameters (entityId, serviceName, workflowName, workflowExecutionId) are provided in the webhook payload. Required headers:

Header	Description
`api_key`	Your FrankieOne API key.
`X-Frankie-CustomerID`	Your FrankieOne customer ID.

Security

HTTPS and IP Whitelisting

All webhook payloads are delivered over HTTPS. FrankieOne supports IP whitelisting so you can restrict incoming requests to known FrankieOne IP addresses. See Outbound IP Addresses for the list of IPs to whitelist.

JWT Authentication (Optional)

You can enable JSON Web Token (JWT) signing for additional payload verification. Contact support@frankieone.com to enable JWT verification for your account. When enabled, the JWT is included in the Authorization header of the webhook request using the Bearer scheme:

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

The JWT has the following structure: Header:

{
  "alg": "RS256",
  "typ": "JWT"
}

Body:

{
  "sub": "[email protected]",
  "iat": 1516239022,
  "iss": "io.frankiefinancial.kycaml"
}

Field	Description
`sub`	The subject. Present for portal-triggered notifications only.
`iat`	Issued-at timestamp (UTC epoch, seconds).
`iss`	Issuer. Fixed value: `io.frankiefinancial.kycaml`.

Security details:

RSA-4096 bit private key encryption.
A customer-specific public key is provided for verification.
HTTPS transport with secure algorithms.

Retry Mechanism

FrankieOne retries failed webhook deliveries using the following approach:

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

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

Best Practices

Respond quickly. Return a 200 or 202 from your webhook endpoint as fast as possible. Perform any heavy processing asynchronously after acknowledging receipt.
Handle duplicates. Due to retries, your endpoint may receive the same notification more than once. Use the requestId field to deduplicate.
Check functionResult. The same function name (e.g., WorkflowComplete, TOKEN_REQUESTED) is used for both success and error events. Always check functionResult to determine the outcome.
Use the retrieval endpoint. Webhook payloads contain summary information. For full workflow execution details, always call the retrieval endpoint using the identifiers provided in the payload.

Migrating from V1

Key differences between V1 and V2 webhook notifications:

Aspect	V1	V2
Function names	`EntityStatusChange`	`EntityStatusChanged`
	`EntityRiskChange`	`EntityRiskChanged`
	`EntityProfileChange`	`EntityProfileUpdated`
	`EntityAssigneeChange`	`EntityAssigneeChanged`
	Per-operation names (e.g., `CreateCheckEntity`)	`WorkflowComplete` (single event for all workflow completions)
Payload fields	`checkId` present in some payloads	`workflowExecutionId`, `workflowName`, `entityType`, `entityCustomerReference`, `serviceName`, `channel` added
Result retrieval	`GET /v1/retrieve/{requestID}`	`GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}`

Introduction

KYC V2 API

Transaction and Activity Monitoring V2 API

KYB V2 API

Core V2 API

Event Notifications & Webhooks

Setup

Available Notifications

Workflow Events

IDV Biometrics Events

Entity Profile Events

Webhook Payload

Payload Fields

Event-Specific Fields

Endpoint Format

Payload Examples

Handling Notifications

1. Receive the Webhook

2. Process the Notification

3. Retrieve Workflow Execution Results

Security

HTTPS and IP Whitelisting

JWT Authentication (Optional)

Retry Mechanism

Best Practices

Migrating from V1

Introduction

KYC V2 API

Transaction and Activity Monitoring V2 API

KYB V2 API

Core V2 API

​Setup

​Available Notifications

​Workflow Events

​IDV Biometrics Events

​Entity Profile Events

​Webhook Payload

​Payload Fields

​Event-Specific Fields

​Endpoint Format

​Payload Examples

​Handling Notifications

​1. Receive the Webhook

​2. Process the Notification

​3. Retrieve Workflow Execution Results

​Security

​HTTPS and IP Whitelisting

​JWT Authentication (Optional)

​Retry Mechanism

​Best Practices

​Migrating from V1

Setup

Available Notifications

Workflow Events

IDV Biometrics Events

Entity Profile Events

Webhook Payload

Payload Fields

Event-Specific Fields

Endpoint Format

Payload Examples

Handling Notifications

1. Receive the Webhook

2. Process the Notification

3. Retrieve Workflow Execution Results

Security

HTTPS and IP Whitelisting

JWT Authentication (Optional)

Retry Mechanism

Best Practices

Migrating from V1