Saltar para o conteúdo principal
Defina 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 é um POST com Content-Type: application/json e este corpo: Por exemplo, uma tarefa do Perplexity concluída (o Perplexity custa 1 crédito):
Uma tarefa com falha também é entregue:
Os preços por tipo de tarefa estão em Créditos e limites.

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:
Uma entrega só vai sem assinatura quando a tarefa não tem chave de API, ou em um lote cuja chave de API foi revogada há mais de 30 dias. Se todas as tarefas que você cria vêm de uma chave de API, rejeite requisições sem assinatura válida.
Depois de fazer a rotação de uma chave, as tarefas enviadas com a nova chave são assinadas com a nova chave. As entregas de tarefas enviadas antes continuam assinadas com a chave que as enviou.

Novas tentativas

Retorne qualquer 2xx 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 com include.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 com POST /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:
O evento é assinado com a chave de API do lote, seu 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.