Webhooks
Callbacks e eventos
O Quality Spy pode notificar sistemas externos conforme o andamento do processamento, permitindo que a aplicação consumidora reaja sem depender apenas de consultas periódicas.
Linha do tempo dos eventos
receivedtranscription_completedtranscription_failedevaluation_completedevaluation_failed
Eventos do processamento
received
Momento: quando o envio é recebido e registrado pela API.
Finalidade: sinalizar que a solicitação entrou no fluxo.
Consumidor: registrar o recebimento e correlacionar o evento ao identificador externo.
transcription_completed
Momento: quando a transcrição é concluída.
Finalidade: indicar que o texto da gravação ficou disponível para as próximas etapas.
Consumidor: atualizar o estado local e seguir aguardando a avaliação, quando aplicável.
transcription_failed
Momento: quando a etapa de transcrição falha.
Finalidade: permitir tratamento operacional da falha.
Consumidor: registrar a falha e acionar o fluxo interno definido para exceções.
evaluation_completed
Momento: quando a avaliação por IA é concluída.
Finalidade: informar que o resultado da avaliação pode ser consumido.
Consumidor: atualizar o status, buscar ou armazenar o resultado conforme o contrato do ambiente.
evaluation_failed
Momento: quando a etapa de avaliação por IA falha.
Finalidade: sinalizar que o processamento não produziu a avaliação esperada.
Consumidor: registrar a falha, manter idempotência e acionar análise ou reprocessamento conforme política interna.
Exemplo de payload
{
"event": "evaluation_completed",
"external_reference": "CALL-001",
"status": "completed",
"occurred_at": "2026-07-09T09:35:00Z"
}Boas práticas para o receptor
- Responder rapidamente com HTTP 2xx.
- Processar o evento em fila própria.
- Implementar idempotência.
- Validar a autenticidade da origem conforme o mecanismo configurado.
- Registrar tentativas sem expor segredos.
- Aceitar reenvios.
- Não depender da ordem perfeita de chegada.
- Correlacionar eventos pelo identificador externo.
Falhas e retentativas
Quando o receptor não confirma o recebimento ou fica indisponível, o fluxo pode prever reenvios conforme a configuração do ambiente. A documentação pública desta página não define quantidade exata de tentativas nem intervalos.
Exemplos de receptor
<?php
$rawBody = file_get_contents('php://input');
$event = json_decode($rawBody, true);
if (!is_array($event)) {
http_response_code(400);
exit;
}
// Valide a origem conforme o mecanismo configurado no ambiente.
// Enfileire o processamento interno e responda rapidamente.
error_log('Callback recebido: ' . ($event['event'] ?? 'evento_desconhecido'));
http_response_code(204);import http from 'node:http';
const server = http.createServer((request, response) => {
if (request.method !== 'POST') {
response.writeHead(405).end();
return;
}
let body = '';
request.on('data', (chunk) => {
body += chunk;
});
request.on('end', () => {
try {
const event = JSON.parse(body);
// Valide a origem conforme o mecanismo configurado no ambiente.
// Enfileire o processamento interno e responda rapidamente.
console.log('Callback recebido:', event.event);
response.writeHead(204).end();
} catch {
response.writeHead(400).end();
}
});
});
server.listen(3000);