메인 콘텐츠로 건너뛰기
태스크에 webhook.url을 지정하면, 태스크가 COMPLETED 또는 FAILED에 도달했을 때 querying.ai가 결과를 그 주소로 POST합니다.

전달 페이로드

각 전달은 Content-Type: application/json인 POST이며 본문은 다음과 같습니다. 예를 들어 완료된 Perplexity 태스크는 다음과 같습니다(Perplexity는 1 크레딧).
실패한 태스크도 전달됩니다.
태스크 유형별 가격은 크레딧과 한도에 있습니다.

서명 검증

API 키로 제출한 태스크는 그 키로 서명됩니다. 각 전달에는 헤더 세 개가 붙습니다. HMAC 키는 태스크를 제출한 API 키(배치라면 배치를 만든 키)의 32바이트 SHA-256 다이제스트입니다. 파싱하기 전의 원본 본문으로 서명을 계산하고, 상수 시간으로 비교하고, 5분 이내의 타임스탬프만 받으세요.
서명되지 않은 전달은 태스크에 API 키가 없을 때, 또는 배치의 API 키가 30일보다 더 전에 폐기되었을 때뿐입니다. 만드는 모든 태스크가 API 키로 제출된다면 유효한 서명이 없는 요청은 거부하세요.
키를 교체한 뒤 새 키로 제출한 태스크는 새 키로 서명됩니다. 그 전에 제출한 태스크의 전달은 여전히 제출에 쓴 키로 서명됩니다.

재시도

수신 확인은 30초 안에 2xx 아무 코드나 반환하면 됩니다. 그 밖의 상태, 타임아웃, 연결 오류는 실패한 시도입니다. 실패한 전달은 2, 4, 8, 16분 뒤에 재시도합니다. 약 30분에 걸쳐 총 다섯 번 시도하며, 모두 같은 querying-webhook-id를 씁니다. 다섯 번째 실패 뒤에는 전달을 포기합니다. 리디렉션은 따라가지 않습니다. 3xx는 실패한 시도로 셉니다. 전달을 거부할 때는 응답 본문에 이유를 넣으세요. 본문 앞 200자가 상태 코드와 함께 저장되고(예: HTTP 400: sources must not be empty), 대시보드와 실패 알림 메일에 표시됩니다. 전달은 태스크와 별개로 실행됩니다. webhook이 끝내 도착하지 않은 태스크도 GET /v1/async/task/{id}에서는 COMPLETED로 보입니다. 복구하려면 비동기 태스크에 설명된 24시간 기간 안에 폴링하세요.

HTML 페이지

include.html로 보낸 태스크도 같은 JSON 본문을 전달합니다. 페이지 자체는 본문에 없습니다. response.html.url이 페이지를 가리키고, 거기서 내려받습니다. 내려받을 때는 API 키가 필요 없고, 요청의 Accept-Encoding이 허용하면 Brotli나 gzip으로 압축되어 오며 압축 방식은 Content-Encoding에 적힙니다. HTML 페이지를 참고하세요.

URL 규칙

webhook.url은 제출 시 검사합니다. 규칙을 어긴 URL은 webhook.url 필드에 대한 400 VALIDATION_ERROR로 거부됩니다. 전달 시점에 호스트는 공개 주소로만 해석되어야 하며, 그렇지 않으면 시도가 실패합니다. 연결은 검사한 그 주소로 이루어집니다.

안전한 핸들러 작성

1

검증한 뒤 빠르게 수신 확인

서명을 확인하고, 페이로드를 영속적으로 저장한 뒤 200을 반환하세요. 파싱과 DB 쓰기는 그 뒤에 해야 느린 핸들러가 30초 타임아웃에 걸려 재시도를 부르지 않습니다.
2

중복 제거

전달은 최소 한 번(at least once) 보장입니다. 이미 처리한 querying-webhook-id의 메시지는 건너뛰거나, task.idempotencyKey로 매칭하고 쓰기를 멱등하게 만드세요.
3

status로 분기

task.status를 명시적으로 확인하세요. 실패한 태스크도 response.error를 담은 webhook을 전달합니다.

배치 완료 이벤트

webhook.url을 지정해 POST /v1/batches로 만든 배치는 각 태스크 결과를 위와 같이 그 URL로 보내고, 모든 항목이 끝나면 완료 이벤트를 한 번 보냅니다.
이 이벤트는 배치의 API 키로 서명되고, querying-webhook-id는 batch_<batch id>이며, 같은 재시도 일정을 따릅니다. 이벤트는 createdAt부터 30일 안, 배치를 조회할 수 있는 동안에만 보냅니다.

다음 단계

비동기 태스크

상태, 폴링, 보관 기간.

배치와 그리드

수천 개 태스크에 webhook URL 하나.