Usando a API do webhook de status do documento

É possível usar o recurso de webhook de status do documento para enviar um evento de webhook para seu aplicativo externo quando o status de documentos alimentados se torna available ou failed O evento webhook ajuda você a executar a próxima ação em documentos indexados, sem precisar obter o status do documento primeiro por meio da API Obter detalhes do documento.

IBM Cloud Pak for DataIBM Software Hub Ao executar o Discovery em um ambiente com air-gap, você deve se conectar ao aplicativo externo por meio de um proxy HTTP. Para obter mais informações, consulte Configuração do proxy HTTP em ambientes com air-gap.

Para usar o recurso webhook de status do documento, faça o seguinte:

  1. Configure o aplicativo externo que pode receber notificações de webhook do Discovery

    Para isso, deve-se registrar seu aplicativo externo como um terminal de webhook em uma coleção usando os métodos de API create collection ou update collection. Para obter mais informações, consulte Criar coleção ou atualizar coleção na referência da API (interface de programação de aplicativos)

    O aplicativo externo recebe um evento ping de webhook, que notifica que o webhook foi criado com sucesso O aplicativo externo deve estar acessível a partir do IBM Cloud

  2. Alimentar os documentos na coleção. Quando o status dos documentos alimentados se torna available ou failed, o aplicativo externo recebe o evento webhook document.status.

    É possível verificar o status dos documentos alimentados no objeto data do evento webhook document.status. Os parâmetros document_ids e status mostram os IDs dos documentos alimentados e seus status.. Para obter mais informações, consulte Modelo de dados do evento ping e Modelo de dados do evento document.status.

A imagem a seguir mostra o fluxo de configuração do webhook.

Mostra o fluxo de configuração do recurso webhook de status do
de configuração do recurso webhook de status do

A imagem a seguir mostra o fluxo do processo do webhook de status do documento.

Mostra o fluxo do processo do recurso webhook de status do
do processo do recurso webhook de status do

Para obter mais informações sobre a API de consulta, consulte Consultar um método de API do projeto na referência da API (interface de programação de aplicativos)

Também é possível consultar o aplicativo webhook-doc-status-sample para o recurso da API do webhook de status do documento Para visualizar o aplicativo de amostra, deve-se ter acesso ao repositório do Discovery doc-tutorial-downloads..

Autenticação da solicitação para segurança do webhook

Para autenticar a solicitação do webhook, verifique o JSON Web Token (JWT) que é enviado com a solicitação. O microserviço de webhook gera automaticamente um JWT e o envia no cabeçalho Authorization com cada chamada de webhook. É sua responsabilidade incluir um código no serviço externo que verifica o JWT.

O sistema pode gerar um JWT com base no sample secret especificado e, no cabeçalho Authorization, é possível transmitir esse JWT gerado pelo sistema para o aplicativo externo. Se você especificar um valor no header, o microsserviço webhook enviará esse valor para o aplicativo externo em vez do JWT.

Por exemplo, se você especificar sample secret no campo Secret do objeto Webhooks nas APIs Criar coleção ou atualizar coleção, poderá incluir um código de amostra como o seguinte em Node.js:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'sample secret');
} catch(err) {
  // error thrown if token is invalid
}

Modelo de dados do evento ping

A seguir estão os parâmetros de evento ping :

evento de ping
Parâmetro Descrição
event O nome do evento é ping
instance_id A ID da instância Discovery.
version A versão da API Discovery no formato yyyy-mm-dd.
data

Um objeto com as informações do evento: url, events, e metadata.

  • url : O ponto de extremidade do webhook configurado ( URL ).

  • events uma matriz de valores de cadeia de caracteres de eventos. Os eventos dessa matriz são enviados para o webhook URL.

  • metadata objeto com informações específicas do webhook criado: Um objeto com informações específicas do webhook criado.
created_at A data e a hora em que o evento foi criado.

Por exemplo, a seguir há um evento ping que é enviado para um webhook:

POST https://example.com/webhook

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
  "event": "ping",
  "version": "2023-03-31",
  "instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
  "data": {
    "url": "https://example.com/webhook",
    "events": [
      "document.status"
    ],
    "metadata": {
      "project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
      "collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b"
    }
  },
  "created_at": "2023-08-16T08:34:46.000Z"
}

Modelo de dados do evento document.status

A seguir estão os parâmetros de evento document.status :

Evento Document.status
Parâmetro Descrição
event O nome do evento é document.status
instance_id A ID da instância Discovery.
version A versão da API Discovery no formato yyyy-mm-dd.
data Um objeto com informações específicas do evento: project_id, collection_id e document_ids.
status O status dos documentos.
created_at A data e a hora em que o evento foi criado.

Por exemplo, a seguir há um evento document.status que é enviado para um webhook:

POST https://example.com/webhook

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
  "event": "document.status",
  "version": "2023-03-31",
  "instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
  "data": {
    "project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
    "collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b",
    "document_ids": [
      "1a5d4916-6097-4150-977a-ca897226565b",
      "2a5d4916-6097-4150-977a-ca897226565b"
    ],
    "status": "available"
  },
  "created_at": "2023-08-16T08:34:46.000Z"
}