webhook.url em uma tarefa e a querying.ai envia o resultado por POST para esse endereço quando a tarefa chega a COMPLETED ou FAILED.
Payload de entrega
Cada entrega é umPOST com Content-Type: application/json e este corpo:
Por exemplo, uma tarefa do Perplexity concluída (o Perplexity custa 1 crédito):
Verificar a assinatura
As tarefas enviadas com uma chave de API são assinadas com essa chave. Cada entrega traz três cabeçalhos:
A chave do HMAC é o digest SHA-256 de 32 bytes da chave de API que enviou a tarefa (em um lote, a chave que criou o lote). Calcule a assinatura sobre o corpo bruto antes de fazer o parsing, compare em tempo constante e aceite timestamps de até cinco minutos:
Novas tentativas
Retorne qualquer2xx em até 30 segundos para confirmar. Qualquer outro status, um timeout ou um erro de conexão é uma tentativa com falha. As entregas com falha são repetidas após 2, 4, 8 e 16 minutos: cinco tentativas ao todo em cerca de 30 minutos, todas com o mesmo querying-webhook-id. Depois da quinta falha, a entrega é abandonada.
Redirecionamentos não são seguidos: um 3xx conta como tentativa com falha.
Ao recusar uma entrega, coloque o motivo no corpo da resposta. Os primeiros 200 caracteres são guardados com o status, por exemplo HTTP 400: sources must not be empty, e aparecem no painel e no e-mail de falha.
A entrega corre separada da tarefa. Uma tarefa cujo webhook nunca chega continua mostrando COMPLETED em GET /v1/async/task/{id}. Para recuperar o resultado, faça polling dentro da janela de 24 horas descrita em Tarefas assíncronas.
Páginas HTML
Uma tarefa enviada cominclude.html entrega o mesmo corpo JSON. A página em si não vem nele: response.html.url aponta para a página, e você a baixa de lá. O download não precisa de chave de API e vem comprimido com Brotli ou gzip, indicado em Content-Encoding, quando o Accept-Encoding da sua requisição permite. Veja Páginas HTML.
Regras de URL
webhook.url é verificada no envio. Uma URL que viola uma regra é rejeitada com 400 VALIDATION_ERROR no campo webhook.url.
No momento da entrega, o host precisa resolver apenas para endereços públicos, ou a tentativa falha. A conexão vai para o endereço que foi verificado.
Escreva um handler seguro
1
Verifique e confirme rápido
Confira a assinatura, armazene o payload de forma durável e retorne
200. Faça o parsing e grave no seu banco de dados depois, para que um handler lento não atinja o timeout de 30 segundos e provoque uma nova tentativa.2
Elimine duplicatas
A entrega é do tipo pelo menos uma vez. Ignore uma mensagem cujo
querying-webhook-id você já processou, ou faça a correspondência por task.idempotencyKey e torne a gravação idempotente.3
Decida pelo status
Verifique
task.status explicitamente. Uma tarefa com falha também entrega um webhook, com response.error.Evento de conclusão do lote
Um lote criado comPOST /v1/batches e um webhook.url envia o resultado de cada tarefa para essa URL como acima e, quando todos os itens terminam, publica um evento de conclusão:
querying-webhook-id é batch_<batch id>, e ele segue o mesmo cronograma de novas tentativas. Ele é enviado só dentro de 30 dias a partir do createdAt do lote, enquanto o lote pode ser lido.
Próximos passos
Tarefas assíncronas
Status, polling e retenção.
Lotes e grades
Uma URL de webhook para milhares de tarefas.