문서 둘러보기
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 바깥쪽 최상위에 배치하세요.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://example.com/webhooks/flashdata"
}{
"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"
}
]
}{
"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}를 호출해 상태를 검증하며, 상태 폴링을 폴백으로 유지하세요.
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);