Using ID&V WebHooks 

Webhooks feature is way for ID&V client to get real-time notifications when a specific event occurs. Event handled by ID&V concerns Evidence or identity status change.

use cases 

To retrieve the Identity Proofing results after evidence verification, two modes are proposed:

  • Polling on getStatus URL: after an evidence is submitted, the client application periodically requests the resource status.

  • Using ID&V WebHook: after an evidence is submitted, the client application waits for a notification indicating the status change.

When pause resume feature is activated, the client application can use the WebHook to be notified when Identity is paused or in error.

This document describes how to use the IDEMIA ID&V WebHook Scenarios.

Sequence 

After each evidence submitted to the identity verification service, ID&V starts a verification process.

As soon as the evidence moves from a transient status to a stable status, the service sends a notification to a predefined URL of the client application.

Transitions from transient status to stable status include :

  • PROCESSING or ADJUDICATION status to a NOT_VERIFIED, VERIFIED or INVALID status

  • NOT_VERIFIED status to VERIFIED or INVALID state,

When transaction expire and pause/resume feature is activated a notification is sent with identify status PAUSED .

WebHooks sequence

Requirements 

Callback URL 

The client application must expose an endpoint (URL) that ID&V uses to send identity verification process notifications. This URL points to a REST API resource with an input corresponding to the ID&V notification request that will be described in the next section.

The notification is a POST Http request as shown in this example: https://example.com/callback

Security 

The developer of the client application must choose one of the supported security modes to secure the notification communication:

  • None: no authentication method
  • API_KEY: a header is added to the notification request containing the value of this key. The name and value of this header should be provided.

Example: Header Name: “APIKey”, Header Value: “aaaa-bbbb-cccc-dddd”

  • HMAC: a secret value must be provided to calculate the HMAC signature. The HMAC signature will be added as a header (header name should be provided).

    Example:

    • Header Name: “hmac”
    • Secret Value: “S3cretW0rd!”

Retry Policy 

By default, ID&V tries three times to post notifications successfully, waiting 10 seconds between each attempt if the previous one failed.

The number of retry and the time to wait between each retry can be configured. The retry mechanism can be described as shown below:

Retry Algo

How to Activate a webhook Notification 

In order to activate the webhook notification perform the following steps:

  • Create a ticket at the Technical Support portal.
  • Fill in the summary field with the value WebHook.
  • In the description text field it's required to provide the:
    • URL of your server
    • Security type between API_KEY or HMAC (recommended).
      • For API_KEY your token is required. A header containing this token will be added to the notification request
      • For HMAC your secret value is required The Hmac signature is calculated from the secret and it will be added to the notification request

Below you can see an example of filled form :

Sample of form

Notification Request 

The service sends a webhook notification back to the integrator when an evaluation is performed on a given evidence or when the identity is paused or error occurs during pause. This happens when the evidence moves from a transient state to a stable state, or from one stable state to another. It can move from:

  • PROCESSING or ADJUDICATION state to a NOT_VERIFIED, VERIFIED or INVALID state

  • NOT_VERIFIED state to VERIFIED or INVALID state

  • VERIFIED state to NOT_VERIFIED or INVALID state

As the portrait is compared to a reference evidence, integrator applications may receive multiple webhooks for PORTRAIT evidence during the process :

  • If the portrait is captured before a reference document is available, its status will be NOT_VERIFIED once the portrait capture is completed.

  • The portrait status may transition to INVALID or VERIFIED when a reference document is available and face comparison has been performed.

  • The reference evidence may change when multiple documents are provided. The portrait status may change from VERIFIED to INVALID, or from INVALID to VERIFIED as the service will perform a new comparison against the new reference

  • Finally, the reference evidence may be deleted. The Portrait status may transition back to NOT_VERIFIED status if there is no other reference document available.

Request 

The request body that ID&V sends to notify the client application contains the data below:

  • businessId - ID&V business ID that was provided at the time of transaction creation. It's used to link the end-user's unique ID with ID&V's unique identity ID as a unique correlation ID.

  • event - Evaluation, IdentityStatusUpdate are possible value

  • identityId - identity ID that will be used for identity requests. This identityId is provided by the identity creation call.

  • identityStatus - current status of identity: PAUSED, ERROR, EXPECTED_INPUT, PROCESSING

  • expireAt - Expiration date of transaction when transaction is paused the date format used is "yyyy-MM-dd'T'HH:mm

    .SSS" in UTC

  • completedAt - processing end time of the evaluation. The date format used is "yyyy-MM-dd'T'HH:mm

    .SSS" in UTC

  • evidenceId - the unique ID of the evidence submitted by the client application. Once the evaluation is completed, the specific evidence can be retrieved by calling ID&V with the appropriate evidenceId.

  • evidenceOperation - type of operation CREATED, DELETED, VERIFY

  • evidenceOperation - type of operation CREATED, DELETED, UPDATED

  • CREATED: notify a creation of the ID evidence once the POST submission request of the evidence is done and evaluation is performed on that evidence.

  • DELETED`: notify a deletion of the ID evidence once the DELETE request of the evidence is done.

  • UPDATED: notify a change of the ID evidence when score or status change after evaluation is performed on that evidence.

Here is an example of the Notification's body

JSON
1{
2  "event": "Evaluation",
3  "identityId": "gips-beda5f8f-fd6e-4a1b-933a-d7105e66ed7c",
4  "identityStatus": "EXPECTING_INPUT",
5  "completedAt": "2020-10-08T11:30:06.768",
6  "evidence": {
7    "evidenceId": "660e3cce-985c-4bfb-af49-9ae3ed369f51",
8    "evidenceType": "PASSPORT",
9    "evidenceOperation": "CREATED"
10  }
11}

The Java POJO related is similar to:

Java
1@Data
2public class NotificationPayload {
3

4    @JsonProperty("businessId")
5    private String businessId;
6    @JsonProperty("event")
7    private EventType event;
8    @JsonProperty("identityId")
9    private String identityId;
10    @JsonProperty("identityStatus")
11    private IdentityStatus identityStatus;
12    @JsonProperty("expireAt")
13    private LocalDateTime expireAt;
14    @JsonProperty("completedAt")
15    private LocalDateTime completedAt;
16    @JsonProperty("evidence")
17    private NotificationEvidence evidence;
18

19    @Data
20    public static class NotificationEvidence {
21        @JsonProperty("evidenceId")
22        private String evidenceId;
23        @JsonProperty("evidenceType")
24        private String evidenceType;
25        @JsonProperty("evidenceOperation")
26        private String evidenceOperation;
27    }
28}

Swagger 

To quickly start an implementation of a webhook, copy the swagger provided here and paste it to swagger editor to generate a server and payload with the language of your choice.

If you develop using Java, the Build Up Server chapter provides an implementation example.

Integrator Notification Processing 

As soon as the Integrator resource receives the callback notification, it should reply with a success http status (20X “200, 201 . . .).

Then the integrator can get the processing results:

  • To get identity content and status, use the identityId: GET https://[URL_MAIN_PART]/gips/v1/identities/[identityId]
  • To get only evidence status, use identityId and evidenceId: GET https://[URL_MAIN_PART]/gips/v1/identities/[identityId]/status/[evidenceId]

Sample Scenario 

Steps:

  1. Create the identity.
  2. Submit Identity document.
  3. Retrieve the Identity.

Sequence diagram:

WebHooks sequence1

Build Up and Test a Quick Notification Java Server 

This tutorial uses a tiny Java server to process the notification webhook. This server will do a few things:

  • Run an embedded jetty server on the port 4567 by using spark library
  • Specify URL routes of the rest API dedicated to receive the notification
  • Upon receiving the notification:
    • Checks the HMAC contained in the header
    • Deserializes the JSON payload to Java POJO
    • Returns http status 200

Download the java server code here.

Configuration of the Server 

The pom.xml of the project includes spark to run the server.

XML
1<dependency>
2       <groupId>com.sparkjava</groupId>
3       <artifactId>spark-core</artifactId>
4       <version>2.5.5</version>
5   </dependency>

For this tutorial, the path URL exposes the secret for the signature, the port of the server, and the header name of the signature.

XML
1secret=secret
2   port=4567
3   headerHmac=x-header-name
4   urlPath=/callback/notification

Define the Spark Route 

This creates a rest resource using spark based on the URL path located in the configuration.

Java
1private static void setupBusinessRoutes() {
2      post(configuration.getUrlPath(), NotificationDemo::handleNotification, new JsonTransformer());
3    }

Receive the Notification 

The method handleNotification is in charge of extracting the HMAC from the header.

This then provides the signature and the computed signature from the payload.

  • If both match, then deserialize the payload to get the identity evidence submitted by the client application.
  • If it does not match, then return the http error code (e.g. 401).
Java
1private static String handleNotification(Request request, Response response) throws IOException {
2      logger.info("received : "  +  request.body() + "\n");
3      String hmac = request.headers(configuration.getHeaderHmac());
4      if(!verifyHash(hmac, request.body())){
5          logger.error("hash is invalid");
6          return error(response);
7      }
8      getEvidenceFromNotication(request);
9      return ok(response);
10    }

Extract the Signature from the Header 

The header of the request notification contains the HMAC. The headerName configuration extracts the signature.

The signature is encoding in a string Base64 value.

Java
1String hmac = request.headers("x-header-hmac");

Calculate the Expected Signature 

The signature is computing from the request body using a SHA256 algorithm and the secret token as a key.

Java
1public static String generateHmac(String payload, String secret, String algo) throws NoSuchAlgorithmException, InvalidKeyException {
2  Mac sha256_HMAC = Mac.getInstance(algo);
3  SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), algo);
4  sha256_HMAC.init(secret_key);
5  return Base64.encodeBase64String(sha256_HMAC.doFinal(payload.getBytes()));
6}

Compare the Signatures 

The notification is processed only if the header HMAC is equal to the computing signature.

Note: Make sure the calculated signature is encoded in Base64.

Java
1public static boolean verifyHash(String signature, String payload) {
2          try {
3              String secret = configuration.getSecret();
4              String computedSignature = SignatureUtils.generateHmac(payload, secret, "HmacSHA256");
5              return signature.equals(computedSignature);
6          } catch (Exception ex) {
7              logger.error("hash is invalid", ex);
8              return false;
9          }
10      }