Saltar al contenido principal
Indica 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 un POST con Content-Type: application/json y este cuerpo: Por ejemplo, una tarea de Perplexity completada (Perplexity cuesta 1 crédito):
Una tarea fallida también se entrega:
Los precios por tipo de tarea están en Créditos y límites.

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:
Una entrega solo va sin firmar cuando la tarea no tiene clave de API, o en un lote cuya clave de API se revocó hace más de 30 días. Si todas las tareas que creas vienen de una clave de API, rechaza las solicitudes sin una firma válida.
Después de rotar una clave, las tareas enviadas con la clave nueva se firman con la clave nueva. Las entregas de tareas enviadas antes siguen firmadas con la clave que las envió.

Reintentos

Devuelve cualquier 2xx 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 con include.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 con POST /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:
El evento se firma con la clave de API del lote, su 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.