Notifications - Webhooks

The Frankie service can be configured to push notifications to a configured endpoint, a’la a webhook.

Notifications can occur in one of 3 ways:

  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
  3. Whenever an entity’s risk level changes e.g. from LOW to HIGH

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 request ID 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 request ID 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 suppliedc by you), then this too will be included in a notification payload where possible.

What to do with a notification

Notification payloads will inform you 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 you follow up with a call to a:
GET [/document/{id}/checks](ref:querydocumentchecks)
or
GET [/entity/{id}/checks](https://apidocs.frankiefinancial.com/reference#queryentitychecks)
to see what information is there.

Configuring a Webhook

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

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.

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"
}

Did this page help you?