Implementation

The database models:

• Company - stores companies and their Onfido configuration.
• User - stores Platform users and a mapping to their Onfido applicant.
• PlatformWebhook - stores webhooks received from the Platform.
• OnfidoWebhook - stores webhooks received from Onfido.
• DocumentType - stores mappings of Platform document-types and Onfido document types.
• Document - stores Platfom documents and a mapping to their Onfido documents.
• Check - stores check data, with a mapping to their Onfido check.

The extension has the following base endpoints:

• /activate/ : handles activation of the extension.
• /deactivate/ : handles deactivation of the extension.

The extension's primary functionality is handled via the following resources:

Document-types endpoints

These endpoints are used to map Rehive document-types to Onfido document types. Clients may choose to name their documents anything and therefore manual mapping of types is required.

• GET, POST : /admin/document-types/
• GET, PATCH, PUT, DELETE : /admin/document-types/<id>/

Each document type in the Onfido extensions consists of the following data:

{
    "id": "string",
    "platform_type": "string",
    "onfido_type": "string",
    "side": "string",
    "created": 0,
    "updated": 0
}

The platform_type is the ID of the document-type in the Rehive Platform.

The onfido_type currently supports the following values:

• national_identity_card
• driving_licence
• passport
• voter_id
• work_permit

The side must either be a null value or front/back value.

Platform webhook endpoint

This endpoint is used to receive events from Rehive. The extension needs to know when certain Platform activity occurs in order to trigger Onfido logic.

• POST : /webhook/

Only the following webhook events need to be sent to this endpoint:

• document.create

This documentation contain info on handling Rehive webhook events.

When a relevant event is received, it is saved to the database where an unique id field on the table ensures that each webhook event is only saved once. Then, the specific event is added to a task queue.

The task queue processes events asynchronously. If the event is document.created the following steps are taken:

1. Create a user in the extension database based on the Platform document's owner:
   • This only happens if the user has not been created yet. Otherwise get the existing user.
2. Create a new Document database entry in the extension for the Platform document.
   • This only happens if a valid document-type mapping can be found for the Platform document-type. If no mapping is found skip the rest of the steps.
   • The Platform document ID is saved along with the document type mapping (so we know which Onfido document this should create).
3. Create a new Document entry in Onfido using the above Document data.
   • Fetch the file URL from the Platform's document.
   • Convert the file into an in-memory-uppload.
   • Upload the file to Onfido along with the applicant ID and appropriate Onfido document type.
   • Save the returned Onfido ID onto the database entry in the extension.
4. Finally, attach the document to a check in the database.
   • If it is a single-sided document then create a new check.
   • If this is a double-sided document, try and find an existing check for the opposite side. If none exists, create one. If the check already exists simply add this document to it as well.
   • The new check does not create its corresponding Onfido check immediately.

After adding the check, some special logic needs to be performed in order to decide "when" to create the check in Onfido. The logic used for processing the addition of Onfido checks is as follows:

1. Post check creation/save (in PENDING) hook:
   • If no checks are currently processing for the applicant
   • Submit the next ready check (if one exists) in FIFO order to Onfido.
2. Post check completion (in FAILED or COMPLETE) hook:
   • If no checks are currently processing for the applicant
   • Submit the next ready check (if one exists) in FIFO order to Onfido.

A ready check is any check that satisfies the multi-side document requirements of the documents in the check. This extension marks these checks with the status PENDING.

Onfido webhook endpoint

This endpoint is used to receive events from Onfido. The extension needs to know when certain Onfido activity occurs in order to trigger extension logic.

• POST : /onfido/webhook/

Only the following webhook events need to be sent to this endpoint:

• check.completed

This documentation contain info on handling Onfido webhook events.

When a relevant event is received, it is saved to the database where an unique id field on the table ensures that each webhook event is only saved once. Then, the specific event is added to a task queue.

The task queue processes events asynchronously. If the event is check.completed the following steps are taken:

1. Try and find a check related to the event object.
   • If no check exists, discontinue processing.
2. If a check is found evaluate the check to see whether the extension data need to be updated according to Onfido.
   • Ensure the extension check has not already been completed
   • Ensure the Onfido check has a "complete" status (complete or withdrawn).
   • For each document in the check, update the corresponding document in the Platform with the status (result) provided by Onfido.
   • Save the check's status in the extension.

NOTE: The current implementation only marks documents as "verified" in the Platform if Onfido marked them as "clear". The following Onfido statuses will be set to "declined" in the Platform: "rejected", "suspected", "caution".

Notes:

• Onfido has very restrictive sandbox throttling rules.
  • 1 request per second with a burst of 2 requests. 30 requests per minute total.
  • As such, the extension has to take into account the possibility that an Onfido request could fail at any arbitrary point.