API de Webhook

A API de Webhook possui funções que dão suporte à postagem de webhooks via operação transcription/start.

Nota

A API Webhook do Transcritor de Diálogos do CPQD disponível em nuvem aceita apenas registros de hooks https devidamente validados. Para mais detalhes, ver a seção de validação de webhooks.

Webhook

Para obter os resultados da transcrição de um arquivo via webhook, é necessário registrá-lo via as operações de início de transcrição, seja por arquivo ou lote. O webhook registrado precisa ter a seguinte API:

Requisição

POST /{audio_id}

Parâmetros da requisição

A requisição deve conter a seguinte variável de path:

  • audio_id: ID do arquivo de áudio cujo resultado será enviado.

O conteúdo postado pelo servidor possui os seguintes campos JSON:

  • event: tipo do evento postado. Os eventos possíveis são:

    • «finished»: caso padrão em que o arquivo foi processado e possui resultado válido.
    • «failed»: caso em que houve falha no processamento de arquivo.
    • «reset»: caso em que o arquivo sofreu a operação de “reset”, tendo ou não este mesmo arquivo emitido «finished» ou «failed» anteriormente.
    • «deleted»: caso em que o arquivo sofreu a operação de “delete”, tendo ou não este mesmo arquivo emitido «finished» ou «failed» anteriormente.

    Nota

    A operação de reset reinicia o arquivo a seu estado inicial, sendo o usuário responsável por registrar os webhooks novamente na nova operação de start.

  • token: token para validação do lado do cliente, caso este tenha registrado um token via operação de validação.

  • error: informação de erro caso o evento emitido tenha sido «failed».

  • result: resultado da transcrição de arquivo em formato JSON.

Resultado

O webhook deverá retornar o código 200 caso a execução seja bem-sucedida. Demais códigos de retorno serão interpretados como erro e devidamente armazenados no campo «warnings» do resultado da transcrição de arquivo.

Who Am I?

Caso o usuário não tenha um domínio registrado em DNS público ou não saiba o seu IP, é possivel usar esta função para o usuário receber seu IP conforme a visibilidade.

Requisição

GET /trd/webhook/whoami

Resultado

O resultado é o hostname do cliente como uma string.

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/webhook/whoami/

Resultado JSON:

"172.20.0.1"

Validar e enviar informações de segurança

Para validação do host de um ou mais webhooks, é possível usar a função de validate, que testa host e porta do webhook.

Requisição

POST /trd/webhook/validate/{host}/{port}

Parâmetros da requisição

A requisição contém a variável de path:

  • host: hostname ou IP do(s) webhook(s) a serem registrados.
  • port: porta do host a ser testada.

O post da requisição possui um corpo JSON com os seguintes campos opcionais:

  • token: token para verificação client-side
  • crt: certificado público em formato PEM

Resultado

O resultado é um booleano dizendo se o par host/porta é visível ao servidor.

Exemplos

Chamada REST (necessário utilitário jq):

curl -X POST http://localhost:8080/trd/webhook/validate/172.20.0.1/8080 \
     -H "Content-Type: application/json" \
     --data "{\"token\": \"a8281f88-1b3c-43b5-8fdf-79c35652e112\", \
              \"crt\": $(jq -Rs . /path/to/certificate.pem)}"

Resultado JSON:

true

SDK - CPQD Transcrição de Diálogos

Como exemplo de implementação em Python para utilização dos webhooks, pode-se utilizar o kit de desenvolvimento para o CPQD Transcrição de Diálogos:

https://github.com/CPqD/trd-sdk-python