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 da Transcrição 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": "6230c8b739231fb289992870", "filename": "nasceu.wav", "status": "COMPLETED", "created_at": "2022-03-15T14:11:19.275000-03:00", "started_at": "2022-03-15T14:11:19.520000-03:00", "diarized_at": "2022-03-15T14:11:20.768000-03:00", "completed_at": "2022-03-15T14:11:21.606000-03:00", "callback_urls": [], "callback_failure_reason": "", "failure_reason": "", "media": { "md5": "18eef3c06a975dc8cd1adad4ae662824", "size": 72544, "input": { "sample_rate": 8000, "channels": 1, "bit_rate": 128000, "format": "Wave", "codec": "PCM", "bandwidth": 3909.2 }, "output": { "redundant_channel": false, "channels": [ { "channel": 1, "duration": 4.531, "speech": 3.2590000000000003, "silence": false } ] } }, "config": { "priority": 50, "normalization": {}, "diarization": { "vad": { "chunk_max_silence": 1200, "chunk_max_length": 3600, "dual_tone": { "enabled": false, "row_freq": [ 350, 697, 770, 852, 941 ], "col_freq": [ 440, 1209, 1336, 1477, 1633 ], "start_time": 0, "stop_time": 5, "min_duration": 0.012 } }, "clustering": { "threshold": -0.4, "enabled": true }, "descriptor": { "enabled": false } }, "recognition": { "lm": "builtin:slm/callcenter-small", "textify": { "enabled": false }, "hints_words": [], "decoder": { "max_sentences": 1, "word_details": 1 }, "tasks": [] } } }, "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.00003584186, "end_time": 0.0898649 }, { "text": "minha", "score": 100, "start_time": 0.0898649, "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.3399758 }, { "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" } ], "task_results": {} } ] }
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' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
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=3' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
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%2F&timeout=2&retries=3' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"token": "a8281f88-1b3c-43b5-8fdf-79c35652e112",
"crt": "-----BEGIN CERTIFICATE-----\n....\n-----END CERTIFICATE-----\n"
}'
Resultado JSON:
{
"reachable": true
}
SDK - 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 a Transcrição de Diálogos:
https://github.com/cpqd/trd-sdk-python