Webhooks

nota

Webhooks integration is recommended over the callback mechanism. Callback integration mechanism will be deprecated in the future.

Intro

Systems that need to receive information related to workflow execution can subscribe to topics of their interest and receive them through a webhook, in asynchronous fashion.

Published events follow the CloudEvents core specification.

The following diagram depicts the sequence of communications for a typical verification process with ID Card capture, face capture, face authentication, liveness detection and ID Card validation:

Communication

A POST request will be sent via HTTPS to the configured URL each time an event related to the subscribed topics is generated.

Example:

After configuring the following webhook data:

Destination URL: https://client-domain.com/webhook
Subscriptions:
- workflows/id-captured/v1

The following requests will be sent:

POST https://client-domain.com/webhook

Content-Type: application/cloudevents+json

{
  "specversion" : "1.0",
  "type": "com.idv_suite.api.workflows.id_captured.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "1195586a-2d7a-41e0-98b2-0bd8c59d8ec6",
  "time": "1970-01-01T00:00:00Z",
  "signature": "UwZpowfzfTqYGGIvM5oeEVMFxz4E1U+SmJ50WT5uad0=",
  "data": {
    "ocr": {
      <document_ocr>
    },
    "assets": [
      {
        "type": "id_front",
        "url": "<cdn_presigned_download_url>"
      },
      {
        "type": "id_back",
        "url": "<cdn_presigned_download_url>"
      },
      {
        "type": "id_portrait",
        "url": "<cdn_presigned_download_url>"
      }
    ]
  }
}

Click here to view the full Webhook OpenAPI Spec

Authentication

Endpoint authentication

The following authentication mechanisms are supported (on the destination URL):

API Key
OAuth 2.0 Client Credentials

Event authentication

HMAC-SHA256 signature is used to authenticate events received via webhook.

All events received via webhook have the signature field:

{
  "specversion": "1.0",
  "type": "com.idv_suite.api.workflows.operation_started.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "2a05b598-715a-424f-8246-f01407fe0505",
  "time": "1970-01-01T00:00:00Z",
  "signature": "v4TGDhEbpyG7TQDMZRjoMXqWj6rFLoxqsO8bAzWHGbc=",
  "data": {
    "customerId": "55a31775-e921-4316-80f6-043b3764e74c"
  }
}

The following example shows how to perform message authentication in Node.js:

import { createHmac } from "node:crypto";

function authenticate(secretKey, event) {
  const { signature, ...rest } = event;

  const digest = createHmac("sha256", secretKey)
    .update(Buffer.from(JSON.stringify(rest), "utf8"))
    .digest("base64");

  return digest === signature;
}

const secretKey = "52b93972-2a96-4dd2-bbcb-ee4233207528";

const event = {
  specversion: "1.0",
  type: "com.idv_suite.api.workflows.operation_started.v1",
  source: "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  id: "2a05b598-715a-424f-8246-f01407fe0505",
  time: "1970-01-01T00:00:00Z",
  signature: "v4TGDhEbpyG7TQDMZRjoMXqWj6rFLoxqsO8bAzWHGbc=",
  data: {
    customerId: "55a31775-e921-4316-80f6-043b3764e74c",
  },
};

console.log(`Authenticated: ${authenticate(secretKey, event)}`);

Webhook topics

The following topics are available for subscription:

workflows/operation-started/v1
workflows/id-captured/v1
workflows/selfie-captured/v1
workflows/facial-authentication-evaluated/v1
workflows/passive-liveness-evaluated/v1
workflows/id-validated/v1
workflows/operation-finished/v1

Events

The following events will be received in case you have subscribed to the corresponding topics:

`workflows.operation_started.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 36
    }
  }
}

Example

{
  "specversion": "1.0",
  "type": "com.idv_suite.api.workflows.operation_started.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "2a05b598-715a-424f-8246-f01407fe0505",
  "time": "1970-01-01T00:00:00Z",
  "signature": "v4TGDhEbpyG7TQDMZRjoMXqWj6rFLoxqsO8bAzWHGbc=",
  "data": {
    "customerId": "55a31775-e921-4316-80f6-043b3764e74c"
  }
}

`workflows.id_captured.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "ocr": {
      "type": "object"
    },
    "assets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["id_front", "id_back", "id_portrait"]
          },
          "url": {
            "type": "string"
          }
        },
        "required": ["type", "url"]
      }
    }
  },
  "required": ["ocr", "assets"]
}

Example

{
  "specversion" : "1.0",
  "type": "com.idv_suite.api.workflows.id_captured.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "1195586a-2d7a-41e0-98b2-0bd8c59d8ec6",
  "time": "1970-01-01T00:00:00Z",
  "signature": "UwZpowfzfTqYGGIvM5oeEVMFxz4E1U+SmJ50WT5uad0=",
  "data": {
    "ocr": {
      <document_ocr>
    },
    "assets": [
      {
        "type": "id_front",
        "url": "<cdn_presigned_download_url>"
      },
      {
        "type": "id_back",
        "url": "<cdn_presigned_download_url>"
      },
      {
        "type": "id_portrait",
        "url": "<cdn_presigned_download_url>"
      }
    ]
  }
}

`workflows.selfie_captured.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "asset": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "pattern": "selfie"
        },
        "url": {
          "type": "string"
        }
      },
      "required": ["type", "url"]
    }
  },
  "required": ["asset"]
}

Example

{
  "specversion": "1.0",
  "type": "com.idv_suite.api.workflows.selfie_captured.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "0629ce0c-6339-4368-beec-b33de0d46c35",
  "time": "1970-01-01T00:00:00Z",
  "signature": "F14hzmqOfpt9DTFrat9kWMlMxXvA3vVCWQoJLTsqY10=",
  "data": {
    "asset": {
      "type": "selfie",
      "url": "<cdn_presigned_download_url>"
    }
  }
}

`workflows.facial_authentication_evaluated.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "Negative",
        "None",
        "NoneBecauseInvalidExtractions",
        "NoneBecausePoseExceed",
        "Positive",
        "Uncertain"
      ]
    },
    "similarity": {
      "type": "number"
    },
    "links": {
      "type": "object",
      "properties": {
        "assets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": ["id_portrait", "nfc_portrait", "selfie"]
              },
              "url": {
                "type": "string"
              }
            },
            "required": ["type", "url"]
          }
        }
      },
      "required": ["assets"]
    }
  },
  "required": ["status", "similarity", "links"]
}

Example

{
  "specversion" : "1.0",
  "type": "com.idv_suite.api.workflows.facial_authentication_evaluated.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "76388be5-0a5c-4efb-9279-bf06cfcd796b",
  "time": "1970-01-01T00:00:00Z",
  "signature": "hn44sXrF+kDaK0cgt7lTVUqT7gX1ActJQbGsouITVrI=",
  "data": {
    "status": "Negative",
    "similarity": 0.0,
    "links": {
      "assets": [
        {
          "type": "id_portrait",
          "url": "<cdn_presigned_download_url>",
        },
        {
          "type": "selfie",
          "url": "<cdn_presigned_download_url>"
        }
      ]
    }
  }
}

`workflows.passive_liveness_evaluated.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "diagnostic": {
      "type": "string",
      "enum": [
        "Live",
        "NoLive",
        "None",
        "NoneBecauseAngleTooLarge",
        "NoneBecauseBadQuality",
        "NoneBecauseEyesClosed",
        "NoneBecauseFaceCropped",
        "NoneBecauseFaceNotFound",
        "NoneBecauseFaceOccluded",
        "NoneBecauseFaceTooClose",
        "NoneBecauseFaceTooCloseToBorder",
        "NoneBecauseFaceTooSmall",
        "NoneBecauseImageDataError",
        "NoneBecauseImagePreprocessError",
        "NoneBecauseInternalError",
        "NoneBecauseLicenseError",
        "NoneBecauseTooManyFaces",
        "Spoof",
        "Uncertain"
      ]
    },
    "links": {
      "type": "object",
      "properties": {
        "assets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": ["selfie"]
              },
              "url": {
                "type": "string"
              }
            },
            "required": ["type", "url"]
          }
        }
      },
      "required": ["assets"]
    }
  },
  "required": ["diagnostic", "links"]
}

Example

{
  "specversion" : "1.0",
  "type": "com.idv_suite.api.workflows.passive_liveness_evaluated.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "7c84f3c5-5b13-4be7-a1ed-16126fd4e34a",
  "time": "1970-01-01T00:00:00Z",
  "signature": "fr9AEoC8LBD7sRiuqLbqPc4WkDQAjORgeqtVy6bIl6M=",
  "data": {
    "diagnostic": "Live",
    "links": {
      "assets": [
        {
          "type": "selfie",
          "url": "<cdn_presigned_download_url>"
        }
      ]
    }
  }
}

`workflows.id_validated.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "validation": {
      "type": "object"
    },
    "links": {
      "type": "object",
      "properties": {
        "assets": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": ["id_front", "id_back"]
              },
              "url": {
                "type": "string"
              }
            },
            "required": ["type", "url"]
          }
        }
      },
      "required": ["assets"]
    }
  },
  "required": ["validation", "links"]
}

Example

{
  "specversion": "1.0",
  "type": "com.idv_suite.api.workflows.id_validated.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "271cfc0d-fa04-4990-95c6-30458b3a3d76",
  "time": "1970-01-01T00:00:00Z",
  "signature": "LGDfmVMJn7cJC9HJGL+wKbjAwKO9e7fUzNsHU7V0nj4=",
  "data": {
    "validation": {
        <document_validation>
    },
    "links": {
      "assets": [
        {
          "type": "id_front",
          "url": "<cdn_presigned_download_url>"
        },
        {
          "type": "id_back",
          "url": "<cdn_presigned_download_url>"
        }
      ]
    }
  }
}

`workflows.operation_finished.v1`

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["DENIED", "EXPIRED", "BLACKLISTED", "SUCCEEDED", "ERROR"]
    },
    "context": {
      "type": "object",
      "properties": {
        "customerId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 36
        }
      }
    }
  },
  "required": ["status", "context"]
}

Example

{
  "specversion": "1.0",
  "type": "com.idv_suite.api.workflows.operation_finished.v1",
  "source": "/operations/85ba1e62-752b-4f83-aa18-01c2c6b008b0",
  "id": "2a05b598-715a-424f-8246-f01407fe0505",
  "time": "1970-01-01T00:00:00Z",
  "signature": "NtBhBXf1+J9i+S5y1YJLmqP3yHqakgip+9IFLQT8Hco=",
  "data": {
    "status": "DENIED",
    "context": {
      "customerId": "55a31775-e921-4316-80f6-043b3764e74c"
    }
  }
}

Intro​

Communication​

Authentication​

Endpoint authentication​

Event authentication​

Webhook topics​

Events​

workflows.operation_started.v1​

workflows.id_captured.v1​

workflows.selfie_captured.v1​

workflows.facial_authentication_evaluated.v1​

workflows.passive_liveness_evaluated.v1​

workflows.id_validated.v1​

workflows.operation_finished.v1​

Intro

Communication

Authentication

Endpoint authentication

Event authentication

Webhook topics

Events

`workflows.operation_started.v1`

`workflows.id_captured.v1`

`workflows.selfie_captured.v1`

`workflows.facial_authentication_evaluated.v1`

`workflows.passive_liveness_evaluated.v1`

`workflows.id_validated.v1`

`workflows.operation_finished.v1`