본문으로 건너뛰기
KO
API 키 받기
문서 둘러보기

API 참조

완료 웹훅

비동기, 배치 및 Bulk 완료 알림을 수신하고 중복 제거 및 검증을 수행합니다.

이 페이지의 내용

callback_url 구성

비동기 쿼리, 배치 항목 또는 Bulk 작업을 제출할 때 포트 443의 공개 HTTPS callback_url(최대 2,048자, 자격 증명 및 URL 프래그먼트 제외)을 지정하세요. 알림을 비활성화하려면 callback_url을 생략하거나 null 또는 빈 문자열을 전달합니다.

비동기 및 배치 요청(POST /v1/queries, POST /v1/queries/batch)에서는 callback_url을 params 바깥쪽의 최상위 쿼리 객체에 배치합니다. Bulk 작업(POST /v2/bulk-jobs)에서는 options 바깥쪽 최상위에 배치하세요.

callback_url이 포함된 비동기 쿼리
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://example.com/webhooks/flashdata"
}
callback_url이 포함된 Bulk 작업
{
  "source": "youtube_metadata",
  "callback_url": "https://example.com/webhooks/flashdata",
  "options": {
    "include_formats": false
  }
}

저장된 콜백 URL vs 요청별 callback_url

Management API는 재사용 가능한 대상을 저장하고 POST /v2/delivery/webhooks/{webhookId}/test로 테스트 페이로드를 보낼 수 있도록 콘솔 관리형 저장 콜백 URL(/v2/delivery/webhooks, cookieSession + csrfToken)도 제공합니다. 프로그래밍 방식의 API 연동에서는 각 요청 제출 시 callback_url을 직접 전달하세요.

이벤트 페이로드 및 헤더

알림은 작업이 completed 또는 failed 상태에 도달했음(또는 Bulk 매니페스트가 게시됨)을 확인해 줍니다. 페이로드에는 쿼리 결과, 미디어 파일, API 키가 절대 포함되지 않습니다. X-Delivery-Id 헤더에도 함께 전달되는 delivery_id로 중복 전달을 제거하세요.

필드의미
delivery_id멱등 중복 제거를 위한 고정 전달 식별자이며 X-Delivery-Id 헤더와 일치합니다.
id작업 또는 Bulk 작업 식별자입니다. 제출 시 저장한 영수증과 대조하세요.
source요청된 데이터 소스(예: google_search 또는 youtube_download).
status종료 상태: 비동기/배치는 completed 또는 failed, Bulk는 매니페스트 게시 후 completed.
links인증이 필요한 Management API 상태 및 결과 링크입니다. 결과를 가져오기 전에 항상 API로 검증하세요.
비동기 / 배치 완료 이벤트
{
  "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"
    }
  ]
}
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"
    }
  ]
}

재시도, 검증 및 수신기 보안

전달은 첫 시도를 포함해 지수 백오프로 총 최대 8회 시도됩니다. delivery_id를 저장한 뒤 즉시 2xx 응답을 반환하세요.

웹훅 이벤트에는 서명이 없습니다. 페이로드의 URL을 무조건 신뢰하거나 임의의 호스트에 요청하지 마세요. id와 source를 저장된 영수증과 대조하고, X-API-Key로 GET /v2/jobs/{id} 또는 GET /v2/bulk-jobs/{bulkId}를 호출해 상태를 검증하며, 상태 폴링을 폴백으로 유지하세요.

최소 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);