Notifications & Webhooks

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

To set up webhooks, have your designated contact email help@frankieone.com. You can configure endpoint collections for:

  • Workflow execution completion

Notification Triggers

Workflow Execution Completion

Triggered when a workflow execution completes.

Webhook Structure

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 for a configurable amount of times over a period of time. The webhook will not be disabled however. If your endpoint returns a 400 status code, the message will not attempt retry.

2

Process the Notification Type

Check the notificationType and function fields to determine the appropriate action.

3

Retrieve a workflow execution result

The workflow execution result can be retrieved at any time post execution by making a request to the GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId} API endpoint.

Additional Security (JWT Authentication)

We secure notification payloads through HTTPS and firewall IP whitelisting. You can also sign your requests with JSON Web Tokens to add an additional layer of security and verify message validity. 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
12}
  • RSA-4096 bit private key encryption
  • Customer-specific public key for verification
  • HTTPS with secure algorithms
  • IP whitelisting

Retry Mechanism

When webhook delivery fails to more than half of the configured endpoints:

  • The system retries delivery every 15 minutes, with up to 50 retries.
  • If all 50 retries fail, the message moves to a Dead Letter Queue (DLQ) and notifies our support team
Built with