> ## Documentation Index > Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ](mailto: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. ## Notification Triggers Triggered when a background request (using `X-Frankie-Background: 1` header) completes. Triggered when an entity's state changes (for example, UNCHECKED → PASS, FAIL → PASS). Triggered when an entity's risk level changes (for example, LOW → HIGH, NULL → LOW). Triggered when an IDV biometrics event occurs (for example, token requested, results retrieved). A single API request may trigger multiple notifications. For example, a background entity verification request could generate three webhooks: 1. Final risk score change 2. Final status change 3. Background process completion ## Webhook Structure ### Endpoint Format FrankieOne appends the `requestID` to your configured webhook endpoint: ```text theme={null} https://your-domain.com/webhook-endpoint/{requestID} ``` ### Payload Examples ```json title="Entity Profile Change Notification" theme={null} { "checkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "documentId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "entityId": "12345678-1234-1234-4321-123487650912", "function": "EntityProfileChange", "functionResult": "COMPLETED", "notificationType": "EVENT", "message": "Profile changed from 'basic_kyc' to 'enhanced_kyc'", "requestId": "01EKVV810DC7NJEC97BAQJZXWR", "version": "1.0.0", "entityCustomerReference": "customer-ref-12345", "linkReference": "https://docs.frankieone.com/reference/retrieve" } ``` ```json title="Entity Assignee Change Notification" theme={null} { "checkId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "entityId": "12345678-1234-1234-4321-123487650912", "function": "EntityAssigneeChange", "functionResult": "COMPLETED", "notificationType": "EVENT", "message": "Entity was reassigned from 'analyst@company.com' to 'reviewer@company.com'", "requestId": "01EKVV810DC7NJEC97BAQJZXWR", "version": "1.0.0", "entityCustomerReference": "customer-ref-12345" } ``` ```json title="Entity Status Change Notification" theme={null} { "checkId": "d4e5f6a7-b8c9-0123-def0-123456789012", "entityId": "12345678-1234-1234-4321-123487650912", "function": "EntityStatusChange", "functionResult": "COMPLETED", "notificationType": "EVENT", "message": "Profile status changed from 'Needs Attention' to 'Passed'", "requestId": "01EKVV810DC7NJEC97BAQJZXWR", "version": "1.0.0", "entityCustomerReference": "customer-ref-12345" } ``` ```json title="Entity OCR Error Notification" theme={null} { "checkId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "entityId": "12345678-1234-1234-4321-123487650912", "function": "OCR_ERROR", "functionResult": "FAILED", "notificationType": "EVENT", "message": "Error encountered while processing OCR data.", "requestId": "01EKVV810DC7NJEC97BAQJZXWR", "version": "1.0.0", "entityCustomerReference": "customer-ref-12345" } ``` ### Payload Fields | Field | Type | Always Present | Description | | ------------------------- | ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `checkId` | string | No | Unique identifier (UUID) for the verification check that triggered the notification. | | `documentId` | string | No | Unique identifier (UUID) of the document associated with the event. | | `entityId` | string | Yes | Unique identifier (UUID) of the entity associated with the event. | | `function` | string | Yes | The specific operation or event that triggered the notification. See [Function Names Reference](#webhook-notification-function-names) for a full list. | | `functionResult` | string | Yes | The outcome of the function. Possible values: `COMPLETED`, `FAILED`. | | `notificationType` | string | Yes | The category of the notification. Possible values: `FUNCTION`, `RESULT`, `EVENT`, `ALERT`. `EVENT` indicates a state or risk change; `FUNCTION` indicates a background process completion; `RESULT` indicates a result notification; `ALERT` indicates an alert notification. | | `message` | string | Yes | A human-readable description of the event. | | `requestId` | string | Yes | Unique identifier (ULID) for the original API request. Use this to retrieve results via the `/retrieve/{requestID}` endpoint. | | `version` | string | Yes | The version of the webhook payload schema. | | `entityCustomerReference` | string | No | Your custom reference identifier for the entity, as provided during entity creation. | | `linkReference` | string | No | URI for resource containing more details about the reason for the notification. | ## Handling Notifications 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. Use the `notificationType` and `function` fields to determine the appropriate action. Retrieve workflow execution results post-execution by calling the `/retrieve` endpoint with the provided `requestID`. ##### When can I `/retrieve` Data? You can access cached API responses via the `/retrieve/{requestID}` endpoint for 7 days. You can retrieve `RequestID`s in two cases: 1. Background/async calls that generate a FUNCTION webhook notification 2. Regular synchronous API calls with a response For state/risk changes, you may want to query additional information using: * `GET /document/{id}/checks` * `GET /entity/{id}/checks` ## 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.** When JWT signing is enabled, FrankieOne includes the token in the `Authorization` header of the webhook HTTP POST request: ```http theme={null} Authorization: Bearer .. ``` The header and body are individually Base64 encoded and joined with a `.` separator. The signature is the Base64-encoded RSA-4096 encryption of the combined header and body. All three parts are concatenated to form the final JWT. ```json theme={null} { "header": { "alg": "RS256", "typ": "JWT" }, "body": { "sub": "agent@email.com", // Portal notifications only "iat": 1516239022, // UTC epoch timestamp in seconds "iss": "io.frankiefinancial.kycaml" // Fixed string } } ``` * RSA-4096 bit private key encryption * Customer-specific public key for verification * HTTPS with secure algorithms * IP whitelisting 1. Extract the JWT from the `Authorization: Bearer` header. 2. Decode the Base64-encoded header and body. 3. Verify the signature using the public key provided by FrankieOne. 4. Validate the `iss` claim matches `io.frankiefinancial.kycaml`. 5. Validate the `iat` claim to ensure the token is not stale. ## 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. ## Webhook Notification Function Names | Webhook function | Reference/Definition | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AssociatedEntityStatusChange | used when there's a change to an associated entity | | BlacklistEntity | Set Entity Blacklist State | | BusinessOwnershipSubscription | (AUS Only) Subscribe or unsubscribe to continuous monitoring of business details and ownership. | | CheckOrganisation | (AUS Only) Run KYC/AML Checks on Organisation and/or Associated Individuals. | | CheckTransactionRisk | When asynchronous KYT transaction check has been sent, this notification is sent when the check has been successfully processed | | CreateAssociateEntity | (AUS Only) Make a new entity a direct associated entity of a parent organisation. | | CreateCheckEntity | Create and Verify Entity | | CreateCheckEntityPushToMobile | Create Entity and Push Self-Verification Link | | CreateDocument | Create New Document. | | CreateEntity | Create New Entity. | | DeleteDocument | Delete Document. | | DeleteEntity | Delete Entity | | DeleteEntityAssociation | (AUS Only) Remove a previously created association between an entity (otherId) and a parent organisation (entityId). | | EntityAMLUpdate | When an AML update is received for an entity | | EntityAssigneeChange | When an entity assignee changes | | EntityMonitoring | Set Entity Ongoing AML Monitoring Status. | | EntityProfileChange | When there's a change to an entity profile recipe | | EntityRiskChange | When an entity risk score changes | | EntityStatusChange | When an entity overall status changes | | FlagDuplicateEntity | Resolve Duplicate States | | InternationalBusinessProfile | (International) Retrieve a business profile from any country. | | InternationalBusinessSearch | (International) Search for a business from any country. | | QueryDocument | Retrieve Document Details | | QueryDocumentChecks | Retrieve Document Verification Check Details. | | QueryDocumentFull | Retrieve Document and Scan Data | | QueryEntity | Retrieve Entity Details | | QueryEntityChecks | [https://docs.frankieone.com/docs/v1/api/kyc-api-endpoints/reference/entity/query-entity](/docs/v1/api/kyc-api-endpoints/reference/entity/query-entity) | | QueryEntityFull | Retrieve Entity Details and Document Scan Data | | QueryOwnershipChecks | (AUS Only) Retrieve previous UBO query results | | QueryParentAssociations | (AUS Only) Retrieve all the parent associations for an Individual or a Business | | RetrieveResult | (Re)retrieve Response Result. | | RunBusinessReports | (AUS Only) Run Report(s) against a new or existing organisation entity. | | RunBusinessReportsMulti | [https://docs.frankieone.com/reference/runbusinessreportsmulti](/docs/v1/api/kyc-api-endpoints/reference/business/run-business-reports) | | SearchDocument | Search For a Document \[Beta] | | UpdateAssociateEntity | (AUS Only) Make an existing entity (otherId) a directly associated entity of a parent organisation (entityId), or update an existing association. | | UpdateCheckEntity | Update Entity and Verify Details | | UpdateCheckEntityPushToMobile | Update Entity and Push Self-Verification Link | | UpdateDocument | Update Existing Document | | UpdateEntity | Update Existing Entity | | UpdateEvaluateEntity | Update Entity and evaluate current results and risk without running any new checks | | UpdateTransactionCase | The notification is sent when a change in status/resolution for an Alert occurs - [https://docs.frankieone.com/reference/patchbulkresolvecases](/api-reference/cases/resolve-cases-for-an-entity) | | UpdateVerifyDocument | Update and Verify Document | | VerifyDocument | Create and Verify Document | | WatchlistEntity | Set Entity Watchlist State | | TOKEN\_REQUESTED | When a token is requested for IDV verification | | RESULTS\_RETRIEVED | When IDV results are retrieved | | OCR\_PROCESSED | When IDV OCR processing is completed | | ONB\_URL\_GENERATED | When an onboarding URL is generated |