KYCFeatures

Event Notifications & Webhooks

FrankieOne provides real-time notifications through webhooks to keep your systems updated about important events and changes.

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.

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 - Coming Soon!

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 FunctionDescription
WORKFLOW_COMPLETESent when a workflow execution finishes, providing the final status and outcome.

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

Notification FunctionDescription
WORKFLOW_ERRORSent when there is an error during workflow execution.

IDV Biometrics Events

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

Notification 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 successfully completed.

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

Notification FunctionDescription
TOKEN_ERRORSent when there is an error during token request for IDV biometrics.
RESULTS_ERRORSent when there is an error retrieving IDV biometrics results.
OCR_ERRORSent when there is an error during OCR processing.
ONB_URL_ERRORSent when there is an error generating the onboarding URL.

Webhook Structure

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": "Workflow has been completed successfully.",
11    "requestId": "01EKVV810DC7NJEC97BAQJZXWR",
12    "version": "2.0.0"
13}

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

GET Workflow Execution Results
1GET /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.

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