Webhooks

/webhooks

Nota Se recomienda la integración mediante Webhooks sobre el mecanismo de callback. El mecanismo de integración por callback quedará obsoleto en el futuro.

---

Introducción

Los sistemas que necesiten recibir información relacionada con la ejecución de flujos de trabajo pueden suscribirse a temas de su interés y recibirlos a través de un webhook, de forma asíncrona.

Los eventos publicados siguen la especificación central de CloudEvents.

El siguiente diagrama describe la secuencia de comunicaciones para un proceso de verificación típico con captura de Documento de Identidad, captura facial, autenticación facial, detección de vida y validación de Documento de Identidad:

text

Cliente Backend
Identity API
Aplicación Cliente (SDK)
Cliente Backend
Identity API
Aplicación Cliente (SDK)
Inicialización SDK
Captura Doc. Identidad
Finalización Operación
Tiempo después
Operación Verificada
Iniciar operación
workflows/operation-started/v1
Enviar Doc. Identidad
workflows/id-captured/v1
Enviar Selfie
workflows/selfie-captured/v1
workflows/facial-authentication-evaluated/v1
workflows/passive-liveness-evaluated/v1
workflows/id-validated/v1
workflows/operation-finished/v1

Comunicación Se enviará una solicitud POST a través de HTTPS a la URL configurada cada vez que se genere un evento relacionado con los temas suscritos.

Ejemplo:

Después de configurar los siguientes datos del webhook:

• URL de destino: https://client-domain.com/webhook

• Suscripciones:

  • workflows/id-captured/v1

Se enviarán las siguientes solicitudes:

text

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

---

Autenticación

Autenticación del endpoint Se admiten los siguientes mecanismos de autenticación (en la URL de destino):

• API Key

• OAuth 2.0 Client Credentials

Autenticación de eventos Se utiliza firma HMAC-SHA256 para autenticar los eventos recibidos a través de webhook.

Todos los eventos recibidos via webhook tienen el campo signature:

json

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

El siguiente ejemplo muestra cómo realizar la autenticación de mensajes en Node.js:

javascript

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(`Autenticado: ${authenticate(secretKey, event)}`);

---

Temas de Webhook

Los siguientes temas están disponibles para suscripción:

• 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

---

Eventos

Se recibirán los siguientes eventos en caso de haberse suscrito a los temas correspondientes:

workflows.operation_started.v1

Esquema

json

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

Ejemplo

json

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

Esquema

json

{
  "$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"]
}

Ejemplo

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

workflows.selfie_captured.v1

Esquema

json

{
  "$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"]
}

Ejemplo

json

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

Esquema

json

{
  "$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"]
}

Ejemplo

json

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

Esquema

json

{
  "$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"]
}

Ejemplo

json

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

Esquema

json

{
  "$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"]
}

Ejemplo

json

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

Esquema

json

{
  "$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"]
}

Ejemplo

json

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