API de Webhook¶
A API de Webhook possui funções que dão suporte à postagem de webhooks via operação job/create
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 no início da transcrição: /trd/v3/job/create. O webhook registrado precisa ter a seguinte API:
Requisição
POST /{job_id}
Parâmetros da requisição
A requisição deve conter a seguinte variável de path:
- job_id: ID do job cujo resultado será recebido.
Resultado em JSON:
{ "job": { "id": "5fc90f68eee464d8c64c7ff7", "filename": "nas.wav", "status": "COMPLETED", "created_at": "2020-12-03T13:16:40.468000-03:00", "started_at": "2020-12-03T13:16:40.576000-03:00", "diarized_at": "2020-12-03T13:16:40.926000-03:00", "completed_at": "2020-12-03T13:16:41.572000-03:00", "tag": "teste", "callback_urls": [], "media": { "md5": "18eef3c06a975dc8cd1adad4ae662824", "size": 72544, "input": { "sample_rate": 8000, "channels": 1, "bit_rate": 128000, "format": "Wave", "codec": "" }, "output": { "redundant_channel": false, "channels": [ { "channel": 1, "duration": 4.531, "speech": 3.2590000000000003, "bandwidth": 4000 } ] } }, "config": { "diarization": { "vad": { "chunk_max_silence": 1200, "chunk_max_length": 3600 }, "clustering":{ "threshold":-0.4, "enabled": true }, "recognition": { "params": {}, "lm": "builtin:slm/callcenter-small" } } }, "segments": [ { "channel": 1, "speaker": "1", "start": 0.861, "end": 4.12, "status": "RECOGNIZED", "alternatives": [ { "text": "a minha filha nasceu hoje ela tem dez anos", "words": [ { "text": "a", "score": 98, "start_time": 0.000314649, "end_time": 0.0899809 }, { "text": "minha", "score": 100, "start_time": 0.0899809, "end_time": 0.45 }, { "text": "filha", "score": 100, "start_time": 0.45, "end_time": 0.87 }, { "text": "nasceu", "score": 100, "start_time": 0.87, "end_time": 1.3199999 }, { "text": "hoje", "score": 100, "start_time": 1.3199999, "end_time": 1.77 }, { "text": "ela", "score": 98, "start_time": 1.86, "end_time": 2.1299999 }, { "text": "tem", "score": 99, "start_time": 2.1299999, "end_time": 2.339976 }, { "text": "dez", "score": 100, "start_time": 2.34, "end_time": 2.6699998 }, { "text": "anos", "score": 100, "start_time": 2.6699998, "end_time": 3.12 } ], "score": 99, "lm": "builtin:slm/callcenter-small" } ] } ] }
- token: token para validação do lado do cliente, caso este tenha registrado um token via operação de validação.
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.
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, é possível usar esta função para o usuário receber seu IP conforme a visibilidade.
Requisição
GET /trd/v3/webhook/whoami
Resultado
O resultado é o hostname do cliente em JSON.
Exemplos
Chamada REST:
curl -X GET http://localhost:8000/trd/v3/webhook/whoami/
Resultado JSON:
{
"address": "192.168.0.10"
}
Validar 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
GET /trd/v3/webhook/validate
Query
- url: hostname ou IP do(s) webhook(s) a serem registrados.
- timeout: tempo entre tentativas (opcional).
- retries: Número de tentativas para enviar a resposta (opcional).
Resultado
O resultado é um booleano dizendo se o par host/porta é visível ao servidor.
Exemplos
Chamada REST, com o webhook: https://example.com/jobs/
curl -X GET "http://localhost:8000/trd/v3/webhook/validate?url=https%3A%2F%2Fexample.com%2Fjobs%2F&timeout=2&retries=10" \
-H "accept: application/json"
Resultado JSON:
{
"reachable": true
}
Enviar informações de segurança¶
Para registro do host de um ou mais webhooks, é possível usar a função de validate.
Requisição
POST /trd/v3/webhook/validate
Query
- url: hostname ou IP do(s) webhook(s) a serem registrados.
- timeout: tempo entre tentativas.
- retries: Número de tentativas para enviar a resposta.
Request Body
- 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:
curl -X POST "http://localhost:8000/trd/v3/webhook/validate?url=https%3A%2F%2Fexample.com%2Fjobs&timeout=2&retries=10" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d "{\"token\":\"a8281f88-1b3c-43b5-8fdf-79c35652e112\",\"crt\":\"-----BEGIN CERTIFICATE-----\....\-----END CERTIFICATE-----\\"}"
Resultado JSON:
{
"reachable": 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