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

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.

Available Notifications

Workflow Events

Notifications triggered when a workflow execution completes, providing updates on the final status and outcome.

IDV Biometrics Events

Notifications for IDV biometrics events, such as token requests, results retrieval, errors, and expirations.

Entity Events

Notifications related to entity events, such as onboarding, updates, and errors.

Workflow Events

FrankieOne sends notifications to keep you informed about workflow events. These notifications are sent to your configured webhook endpoint.

Notification Function	Description
`WorkflowComplete`	Sent when a workflow execution finishes, providing the final status and outcome.

Workflow Error Events

Notifications related to errors workflow events are sent to your webhook endpoint.

Notification Function	Description
`WorkflowComplete`	Sent when there is an error during workflow execution.

IDV Biometrics Events

Notifications related to IDV biometrics events are sent to your webhook endpoint.

Notification Function	Description
`IDVTokenRequested`	Sent when a token is requested for IDV biometrics.
`OnbTokenRequested`	Sent when an onboarding URL is successfully generated.
`IDVResultsRetrieved`	Sent when IDV biometrics results are successfully retrieved.
`IDVOCRProcessing`	Sent when OCR processing is successfully completed.

IDV Biometrics Error Events

Notifications related to errors in IDV biometrics events are sent to your webhook endpoint.

Notification Function	Description
`IDVTokenRequested`	Sent when there is an error during token request for IDV biometrics.
`IDVResultsRetrieved`	Sent when there is an error retrieving IDV biometrics results.
`IDVOCRProcessing`	Sent when there is an error during OCR processing.
`OnbTokenRequested`	Sent when there is an error generating the onboarding URL.

Entity Profile Events

FrankieOne sends notifications to keep you informed about entity profile events. These notifications are sent to your configured webhook endpoint.

Notification Function	Description
`EntityProfileUpdated`	Sent when an entity profile is updated, providing the latest information.
`EntityRiskChanged`	Sent when there is a change in the risk status of an entity profile.
`EntityStatusChanged`	Sent when the status of an entity profile changes, such as onboarding or verification.
`EntityAssigneeChanged`	Sent when the assignee of an entity profile changes, indicating a new point of contact.

Webhook Structure

All V2 webhooks share a consistent structure. The payload contains two key fields, notificationType and function, which you should use to determine how to process the event.

notificationType: Indicates the nature of the update. For most V2 use cases, this will be EVENT.

function: This field specifies the exact event that occurred. All function names use PastTense.

The payload for every webhook consists of a base schema of common fields, with additional event-specific fields included depending on the function.

Base Payload Schema

These fields are present on every webhook notification.

Attribute	Type	Description
version	string	The API version of the webhook event.
notificationType	string	The category of notification (e.g., EVENT, RESULT).
function	string	The specific event that triggered the notification (e.g., WorkflowComplete).
functionResult	string	Indicates if the event was successful (SUCCESS) or not (ERROR, FAILURE).
requestId	string	The unique ID for the API request that initiated the event.
entityId	string	The unique identifier of the entity related to the event.
entityType	string	The type of the entity (e.g., INDIVIDUAL).
entityCustomerReference	string	A reference identifier for the customer, used for linking notifications to your internal records.
serviceName	string	The name of the service profile involved.
message	string	A human-readable summary of the event.
channel	string	The channel source from which the webhook was triggered (e.g., API, WEBHOOK).

Event-Specific Fields

Depending on the function, additional fields will be present in the payload to provide specific context.

Function	Additional Field(s)	Description
WorkflowComplete	workflowExecutionId, workflowName	Provides the final status and identifiers of a completed workflow.
EntityStatusChanged	overallStatus	Provides the new status of the entity profile.
EntityRiskChanged	overallRiskStatus	Provides the new risk level of the entity profile.

You can choose to receive all or specific notifications based on your needs. The notificationType field in the payload indicates the type of notification.

Endpoint Format

FrankieOne appends the requestID to your configured webhook endpoint:

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

Payload Examples

State Change Notification

1 {
2     "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
3     "entityId": "12345678-1234-1234-4321-123487650912",
4     "entityType": "INDIVIDUAL",
5     "workflowName": "Onboarding",
6     "serviceName": "KYC",
7     "function": "WorkflowComplete",
8     "functionResult": "SUCCESS",
9     "notificationType": "EVENT",
10     "message": "Entity profile updated",
11     "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
12     "version": "2.0.0",
13     "entityCustomerReference": "customer-ref-12345",
14     "overallStatus": "COMPLETED",
15     "channel": "api"
16 }

Risk Change Notification

1 {
2     "workflowExecutionId": "01JMX7F1Z61K0BP0KWY6MWAQ4J",
3     "entityId": "12345678-1234-1234-4321-123487650912",
4     "entityType": "INDIVIDUAL",
5     "workflowName": "Onboarding",
6     "serviceName": "KYC",
7     "function": "EntityRiskChanged",
8     "functionResult": "SUCCESS",
9     "notificationType": "EVENT",
10     "message": "Entity profile updated",
11     "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
12     "version": "2.0.0",
13     "entityCustomerReference": "customer-ref-12345",
14     "overallRiskStatus": "LOW",
15     "channel": "api"
16 }

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 anytime post-execution by calling the following API endpoint:

GET Workflow Execution Results

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

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": "io.frankiefinancial.kycaml"  // 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.