Skip to main content

​
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 [email protected] 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

FunctionDescription
WorkflowCompleteSent 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

FunctionDescription
TOKEN_REQUESTEDSent when a token is requested for IDV biometrics.
ONB_URL_GENERATEDSent when an onboarding URL is successfully generated.
RESULTS_RETRIEVEDSent when IDV biometrics results are successfully retrieved.
OCR_PROCESSEDSent 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

FunctionDescription
EntityStatusChangedSent when the overall status of an entity profile changes.
EntityRiskChangedSent when the risk level of an entity profile changes.
EntityProfileUpdatedSent when an entity profile is updated.
EntityAssigneeChangedSent 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 tables above for the correct V2 function names.

​
Webhook Payload

​
Base Payload Fields

These fields are present on every webhook notification.
FieldTypeDescription
versionstringThe API version of the webhook payload.
notificationTypestringThe category of notification (e.g., EVENT).
functionstringThe specific event that triggered the notification (e.g., WorkflowComplete).
functionResultstringThe outcome of the event. See functionResult Values below.
requestIdstringThe unique identifier of the API request that initiated the event.
entityIdstringThe unique identifier of the entity related to the event.
entityTypestringThe type of entity (e.g., INDIVIDUAL).
entityCustomerReferencestringYour customer reference identifier, used for linking notifications to your internal records.
serviceNamestringThe name of the service profile involved.
messagestringA human-readable summary of the event.
channelstringThe channel source from which the webhook was triggered.

​
functionResult Values

The functionResult field indicates the outcome of the event.
ValueDescription
SUCCESSThe event completed successfully.
ERRORUnexpected System Error contact support
FAILUREUnexpected System Failure contact support

​
Event-Specific Fields

Depending on the function, additional fields may be present in the payload.
FunctionAdditional FieldsDescription
WorkflowCompleteworkflowExecutionId, workflowName, overallStatusIdentifiers and final status of the completed workflow.
EntityStatusChangedoverallStatusThe new overall status of the entity profile.
EntityRiskChangedoverallRiskStatusThe new risk level of the entity profile.
overallStatus corresponds to the workflow execution result. Possible values from the OpenAPI spec (Workflow-Execution-ResultEnum): UNCHECKED · IN_PROGRESS · REVIEW · PASS · FAIL · COMPLETE · INCOMPLETE · NEEDS_APPROVAL · APPROVED · REJECTED · BLOCKED · CLEAR · URGENT · MONITOR overallRiskStatus corresponds to the risk level. Possible values from the OpenAPI spec (Risk-Level): UNKNOWN · LOW · MEDIUM · HIGH · UNACCEPTABLE

​
Endpoint Format

FrankieOne appends the requestID to your configured webhook endpoint: 
https://your-domain.com/webhook-endpoint/{requestID}

​
Payload Examples

​
Workflow Complete (Success)

{
  "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"
}

​
Entity Risk Changed

{
  "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
  "entityId": "12345678-1234-1234-4321-123487650912",
  "entityType": "INDIVIDUAL",
  "workflowName": "Onboarding",
  "serviceName": "KYC",
  "function": "EntityRiskChanged",
  "functionResult": "SUCCESS",
  "notificationType": "EVENT",
  "message": "Entity profile updated",
  "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
  "version": "2.0.0",
  "entityCustomerReference": "customer-ref-12345",
  "overallRiskStatus": "LOW",
  "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:
HeaderDescription
api_keyYour FrankieOne API key.
X-Frankie-CustomerIDYour 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.

​
JWT Authentication (Optional)

You can enable JSON Web Token (JWT) signing for additional payload verification. Contact [email protected] to enable JWT verification for your account. When enabled, webhook payloads include a JWT with the following structure: Header: 
{
  "alg": "RS256",
  "typ": "JWT"
}
Body: 
{
  "sub": "[email protected]",
  "iat": 1516239022,
  "iss": "io.frankiefinancial.kycaml"
}
FieldDescription
subThe subject. Present for portal-triggered notifications only.
iatIssued-at timestamp (UTC epoch, seconds).
issIssuer. 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:
  1. Initial Retry: Immediately after the first failure.
  2. Exponential Backoff: Subsequent retries occur at increasing intervals.
  3. 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 [email protected] 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:
AspectV1V2
Function namesEntityStatusChangeEntityStatusChanged
EntityRiskChangeEntityRiskChanged
EntityProfileChangeEntityProfileUpdated
EntityAssigneeChangeEntityAssigneeChanged
IDVTokenRequestedTOKEN_REQUESTED
IDVResultsRetrievedRESULTS_RETRIEVED
IDVOCRProcessingOCR_PROCESSED
Per-operation names (e.g., CreateCheckEntity)WorkflowComplete (single event for all workflow completions)
Payload fieldscheckId present in some payloadsworkflowExecutionId, workflowName, entityType, entityCustomerReference, serviceName, version, channel added
Result retrievalGET /v1/retrieve/{requestID}GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}