Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Referência da API

Webhooks de conclusão

Receba, deduplique e verifique notificações de conclusão para tarefas assíncronas, em lote e Bulk.

Nesta página

Configurar callback_url

Forneça uma callback_url HTTPS pública na porta 443 (até 2.048 caracteres, sem credenciais ou fragmento de URL) ao enviar consultas assíncronas, itens em lote ou tarefas Bulk. Omita callback_url ou envie null ou uma string vazia para desativar notificações.

Em solicitações assíncronas e em lote (POST /v1/queries e POST /v1/queries/batch), coloque callback_url no nível superior do objeto da consulta, fora de params. Em tarefas Bulk (POST /v2/bulk-jobs), coloque callback_url no nível superior, fora de options.

Consulta assíncrona com callback_url
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
Tarefa Bulk com callback_url
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

URLs de callback salvas vs. callback_url por solicitação

A Management API também expõe URLs de callback salvas gerenciadas pelo console em /v2/delivery/webhooks (cookieSession + csrfToken) para salvar destinos reutilizáveis e enviar payloads de teste via POST /v2/delivery/webhooks/{webhookId}/test. Integrações programáticas via API devem informar callback_url diretamente em cada envio.

Payloads de eventos e cabeçalhos

As notificações confirmam que uma tarefa atingiu completed ou failed (ou que o manifesto Bulk foi publicado). Os payloads nunca contêm resultados de consulta, arquivos de mídia nem sua chave de API. Deduplique entregas usando delivery_id (também enviado no cabeçalho X-Delivery-Id).

CampoSignificado
delivery_idIdentificador de entrega estável para deduplicação idempotente; corresponde ao cabeçalho X-Delivery-Id.
idIdentificador da tarefa ou tarefa Bulk. Compare com o recibo salvo no envio.
sourceFonte de dados solicitada (por exemplo, google_search ou youtube_download).
statusEstado final: completed ou failed para async/batch; completed para Bulk após a publicação do manifesto.
linksLinks autenticados de status e resultados da Management API. Sempre verifique via API antes de buscar os resultados.
Evento de conclusão assíncrono / em lote
{
  "delivery_id": "dlv_01JEXAMPLE0000000000000000",
  "id": "job_01JEXAMPLE0000000000000000",
  "source": "google_search",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_01JEXAMPLE0000000000000000/results",
      "method": "GET"
    }
  ]
}
Evento de conclusão Bulk
{
  "delivery_id": "dlv_01JEXAMPLE0000000000000001",
  "id": "bulk_01JEXAMPLE0000000000000000",
  "source": "youtube_metadata",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000",
      "method": "GET"
    },
    {
      "rel": "manifest",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_01JEXAMPLE0000000000000000/manifest",
      "method": "GET"
    }
  ]
}

Tentativas, verificação e segurança do receptor

A entrega tenta até oito vezes no total, incluindo a primeira tentativa, com backoff exponencial. Retorne uma resposta 2xx prontamente após salvar delivery_id.

Eventos de webhook não são assinados. Nunca confie cegamente nas URLs do payload nem faça requisições a hosts arbitrários: compare id e source ao recibo salvo, verifique o status via GET /v2/jobs/{id} ou GET /v2/bulk-jobs/{bulkId} com X-API-Key e mantenha o polling de status como fallback.

Receptor mínimo de webhook em Node.js
import http from "node:http";

const seen = new Set(); // Replace with durable database storage in production.

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/webhooks/flashdata") {
    res.writeHead(404).end();
    return;
  }
  const chunks = [];
  req.on("data", chunk => chunks.push(chunk));
  req.on("end", () => {
    const event = JSON.parse(Buffer.concat(chunks).toString("utf8"));
    const deliveryId = String(req.headers["x-delivery-id"] ?? event.delivery_id ?? "");
    if (!deliveryId || seen.has(deliveryId)) {
      res.writeHead(200).end("ok");
      return;
    }
    seen.add(deliveryId);
    // Queue background verification against https://api.flashdata.dev/v2/jobs/{id}
    // or /v2/bulk-jobs/{id} with X-API-Key; ignore unverified URLs in event.links.
    res.writeHead(200).end("accepted");
  });
}).listen(3000);