webhook.url en una tarea y querying.ai envía allí el resultado por POST cuando la tarea llega a COMPLETED o FAILED.
Payload de entrega
Cada entrega es unPOST con Content-Type: application/json y este cuerpo:
Por ejemplo, una tarea de Perplexity completada (Perplexity cuesta 1 crédito):
Verifica la firma
Las tareas enviadas con una clave de API se firman con esa clave. Cada entrega lleva tres encabezados:
La clave HMAC es el digest SHA-256 de 32 bytes de la clave de API que envió la tarea (en un lote, la clave que creó el lote). Calcula la firma sobre el cuerpo sin procesar antes de parsearlo, compara en tiempo constante y acepta marcas de tiempo de hasta cinco minutos:
Reintentos
Devuelve cualquier2xx en 30 segundos para confirmar. Cualquier otro estado, un timeout o un error de conexión es un intento fallido. Las entregas fallidas se reintentan a los 2, 4, 8 y 16 minutos: cinco intentos en total durante unos 30 minutos, todos con el mismo querying-webhook-id. Tras el quinto fallo la entrega se abandona.
Las redirecciones no se siguen: un 3xx cuenta como intento fallido.
Si rechaza una entrega, ponga el motivo en el cuerpo de la respuesta. Los primeros 200 caracteres se guardan con el estado, por ejemplo HTTP 400: sources must not be empty, y aparecen en el panel y en el correo de fallo.
La entrega se ejecuta aparte de la tarea. Una tarea cuyo webhook nunca llega sigue mostrando COMPLETED en GET /v1/async/task/{id}. Para recuperarla, sondea dentro de la ventana de 24 horas descrita en Tareas asíncronas.
Páginas HTML
Una tarea enviada coninclude.html entrega el mismo cuerpo JSON. La página no va dentro: response.html.url enlaza a la página, y la descargas desde ahí. La descarga no necesita clave de API y llega comprimida con Brotli o gzip, indicado en Content-Encoding, cuando el Accept-Encoding de tu petición lo permite. Consulta Páginas HTML.
Reglas de la URL
webhook.url se comprueba al enviar. Una URL que incumple una regla se rechaza con 400 VALIDATION_ERROR sobre el campo webhook.url.
En el momento de la entrega, el host debe resolverse solo a direcciones públicas o el intento falla. La conexión va a la dirección que se comprobó.
Escribe un handler seguro
1
Verifica y confirma rápido
Comprueba la firma, guarda el payload de forma persistente y devuelve
200. Haz el parseo y las escrituras en base de datos después, para que un handler lento no agote el timeout de 30 segundos y provoque un reintento.2
Deduplica
La entrega es de tipo «al menos una vez». Omite un mensaje cuyo
querying-webhook-id ya hayas procesado, o compara por task.idempotencyKey y haz la escritura idempotente.3
Ramifica por estado
Comprueba
task.status de forma explícita. Una tarea fallida también entrega un webhook, con response.error.Evento de finalización del lote
Un lote creado conPOST /v1/batches y un webhook.url envía el resultado de cada tarea a esa URL como se describe arriba y después publica un evento de finalización cuando todos los elementos han terminado:
querying-webhook-id es batch_<batch id> y sigue el mismo calendario de reintentos. Se envía solo dentro de los 30 días desde el createdAt del lote, mientras el lote se puede leer.
Siguientes pasos
Tareas asíncronas
Estados, sondeo y retención.
Lotes y cuadrículas
Una URL de webhook para miles de tareas.