Notifications - Webhooks

The FrankieOne service can be configured to push notifications to a configured endpoint, like a webhook.

A notification will be sent for each of the following 3 triggers:

1. When an API user requests a process to run in the background using the X-Frankie-Background: 1 header.

2. Whenever an entity’s state changes, e.g. from FAIL to PASS, UNCHECKED to PASS.

3. Whenever an entity’s risk level changes e.g. from LOW to HIGH, NULL to LOW.

A single API request may result in multiple notifications being sent if there are multiple triggers. For example, an API call made to create & verify an entity with the X-Frankie-Background: 1 set would result in a total of 3 webhooks being sent at the end of the check:

1. For the FINAL risk score change. (e.g 0->31).
2. For the FINAL status change. (UNCHECKED -> PASS).
3. For the fact the backgrounded/asynchronous call has been completed.

An entity is assigned an initial risk score when it is created, which may change depending on the outcome of the assigned checks. It should be noted that only the final and overall change to the risk score is sent as a webhook. E.g (0->10, 10->31, would be sent as 0->31).

Notifications are pushed to a configured endpoint using the following format described here in the API Reference

📘

Appending the RequestID

The FrankieOne service appends the requestID to your configured endpoint in each notification.
e.g If your endpoint is https://demo.domain.io/pushnotification/ then the POST request that FrankieOne will send through for requestID 01EKVV810DC7NJEC97BAQJZXWR will be:

https://demo.domain.io/pushnotification/01EKVV810DC7NJEC97BAQJZXWR

The payload pushed provides a number of key items such as a requestID, entityId, and other summary information. It is then the responsibility of the Customer’s service to act upon these notifications and retrieve the relevant data via the API or have a human review the change via the portal.

If the relevant entity also has a customer_reference (i.e. an ID supplied by you), then this too will be included in a notification payload where possible.

What to do with a notification

Notification payloads will inform of the details of what has happened at a high level.

In the case of backgrounded operations, you should call the /retrieve operation using the RequestID given in both the original 202 response and also in the notification.

The /retrieve function will return the HTTP code and payload that would have been sent to you if you had waited for the response.

Event payloads (when state/risk changes) will also contain entity/document details along with a brief description of what has changed. In this case, it is recommended that following up with a call to a:
GET [/document/{id}/checks] is made,
or
GET [/entity/{id}/checks]
to see what information is there.

Configuring a Webhook

Webhook configuration is set up by the FrankieOne technical support team. Please have your designated contacts reach out to [email protected] and we can arrange to have these set up for you.

📘

Responding to FrankieOne

Your endpoint should respond with a 200 or a 202 http response to let FrankieOne know that the message has been accepted.

4XX or 5XX responses where you've would result in the notifications being retried erroneously

It's actually possible to push notifications to a collection of endpoints if you need more than one system to be notified of events.

We can set up to 3 separate notification endpoint collections to receive the notification payload:

1. One group for backgrounded function notifications.
2. Another for "event" notifications where there is a risk change.
3. And a collection for "result" notifications when a check process is finalised.

Notification endpoints can also be email addresses where the notification payload can be sent with minimal formatting. We only offer this in very low volume or test environments.

Notification Retries

If less than 50% of the provided endpoints successfully consume the webhook, FrankieOne will try to send it through again in 15 minutes time. It will continue to do this up to 50 times, after which it will be shifted to a DLQ and an internal alert raised.

Example Notifications

1. When there has been an update that indicates a state change

{
    "checkId": "11111111-2222-3333-4444-555555555555",
    "entityId": "12345678-1234-1234-4321-123487650912",
    "function": "UpdateCheckEntity",
    "functionResult": "COMPLETED",
    "notificationType": "EVENT",
    "requestId": "01EKVV810DC7NJEC97BAQJZXWR"
}

2. When there has been a risk level change

{
    "entityId": "12345678-1234-1234-4321-123487650912",
    "function": "EntityRiskChange",
    "functionResult": "COMPLETED",
    "notificationType": "EVENT",
    "requestId": "01EKVV9BNVNE1KFZ7PBPWGZJZH",
    "message": "Risk score changed from 0 to 19"
}