튜토리얼

hiapi 작업 콜백이 트리거되지 않는 이유와 해결 방법

Jun 26, 2026

hiapi 작업 콜백이 트리거되지 않는 이유

POST https://api.hiapi.ai/v1/tasks에 callback 객체를 포함하여 작업을 제출했고, 작업이 완료되었습니다(GET /v1/tasks/{taskId} 시 status: "success" 확인 가능). 그러나 엔드포인트는 최종 상태 알림을 받지 못했습니다. 서버에 도달한 요청이 없습니다. 재시도도 없습니다. 로그에도 아무것도 없습니다.

hiapi 콜백은 네트워크 외부에서 서버 간 HTTPS POST 방식으로 전송됩니다. 이 경로에서 문제가 발생하면—URL이 공인 인터넷에서 접근 불가능하거나, TLS 협상이 실패하거나, 핸들러가 충분히 빠르게 2xx를 반환하지 않거나, 서명 검증이 요청을 거부하면—앱 입장에서는 알림이 "조용히" 사라진 것입니다. 좋은 소식은 이것이 거의 항상 소수의 잘못된 설정 중 하나이며, 각각 쉽게 검증할 수 있다는 점입니다.

일반적인 원인(가능성 순)

콜백 URL이 공인 인터넷에서 접근 불가능합니다. localhost, 127.0.0.1, VPC 내부 IP, 또는 만료된 ngrok 터널은 hiapi에서 접근할 수 없습니다.
HTTPS / TLS 문제. 자체 서명 인증서, 만료된 인증서, 누락된 중간 인증서, 또는 호스트名 불일치. hiapi는 https://로 시작하는 URL에만 POST를 수행하며 인증서 체인을 검증합니다.
핸들러가 제한 시간 내에 2xx를 반환하지 않습니다. 콜백 핸들러에서 동기적으로 시간이 오래 걸리는 작업(DB 쓰기, 이미지 다운로드, 알림 전송)을 수행하면 200을 반환하기 전에 요청이 타임아웃됩니다. hiapi 입장에서는 이것이 실패입니다.
Webhook Sign Key를 등록하지 않았고 핸들러가 서명되지 않은 요청을 거부합니다. Settings에서 서명 키를 생성하지 않으면 hiapi가 전송하는 요청 본문에 서명 헤더가 없습니다—작성한 검증 미들웨어는 해당 요청을 무효로 간주하고 버립니다.
제출 시 callback 객체를 누락했습니다. 이는 선택 사항입니다. POST /v1/tasks 시 포함하지 않았다면 트리거될 것이 없습니다. 대신 GET /v1/tasks/{taskId}를 폴링해야 합니다.
작업이 아직 실행 중입니다. 콜백은 최종 상태(success 또는 fail)에서만 트리거됩니다. status가 queued, handling, archiving인 동안에는 콜백이 전송되지 않습니다.
콜백 URL의 호스트가 차단 목록에 있거나 회사 방화벽이 해당 호스트로의 아웃바운드 트래픽을 차단합니다. 흔하지는 않지만 엄격한 경계 네트워크 환경에 있다면 확인해 볼 가치가 있습니다.

해결 방법: 7단계 체크리스트

작업이 실제로 최종 상태에 도달했는지 확인하세요. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... status가 queued 또는 handling이면 콜백은 아직 트리거되지 않았습니다—기다리세요, 디버깅하지 마세요.
callback 객체를 제출했는지 확인하세요. POST /v1/tasks에 보낸 요청 본문을 다시 읽어보세요. callback이 빠졌다면 그것이 답입니다—추가하고 다시 제출하거나 폴링으로 전환하세요.
공인 인터넷에서 콜백 URL을 테스트하세요. 네트워크 외부의 머신(셀룰러 네트워크의 휴대폰, 클라우드 셸, 온라인 curl 도구)에서 curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json"을 실행하세요. 서버에서 HTTP 2xx 응답을 받아야 합니다. 연결 거부, DNS 오류, 또는 2xx가 아닌 응답이 나오면 먼저 이를 수정하세요.
TLS 인증서 체인을 검증하세요. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. SSL certificate problem을 찾으세요. 이 오류가 보이면 전체 인증서 체인(리프 인증서 + 중간 인증서)을 설치하거나 관리형 인증서(Let's Encrypt, CDN, ACM)를 사용하세요.
즉시 200을 반환하고 비동기적으로 처리하세요. 핸들러 내부에서: 요청 페이로드를 큐/데이터 테이블에 쓰고, 200 OK를 반환한 뒤, 백그라운드 워커에서 작업을 처리하세요. 느린 다운스트림 호출이 응답을 차단하게 하지 마세요.
Webhook Sign Key를 생성하고 검증 방식을 통일하세요. /en/dashboard/settings → Webhook Sign Key → Generate로 이동하여 키를 저장하세요. 핸들러가 서명을 검증한다면 저장된 키를 사용하세요; 검증하지 않는다면 일시적으로 검증을 비활성화하여 전송이 정상인지 확인한 후 다시 활성화하세요.
/en/dashboard/logs를 확인하세요. 호출 로그에 요청과 최종 상태가 표시됩니다. 호출 로그의 request_id를 서버가 실제로 수신한 내용(있다면)과 비교하는 것이 "콜백이 hiapi를 떠났는지"와 "콜백이 내 서버에 도달했는지"를 가장 빠르게 구분하는 방법입니다.

최소 검증 예제

다음을 사용하여 API 키, 작업 생성 경로, 콜백 엔드포인트를 엔드투엔드로 확인하세요. 빠른 이미지 모델로 스모크 테스트를 수행하세요; 공개 문서에 따르면 모델 ID에는 기능 접미사가 포함됩니다:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {"prompt": "a cute cat"},
    "callback": {"url": "https://your.domain.example/hiapi/callback"}
  }'

즉시 tk-hiapi-... 형태의 taskId가 포함된 JSON 응답을 받아야 합니다. 그런 다음 작업이 success 또는 fail이 되면 서버 로그에서 /hiapi/callback으로의 인바운드 POST가 있는지 관찰하세요. 작업 생성 단계 자체가 401 Unauthorized를 반환하면 키 문제입니다—hiapi의 오류 봉투 메커니즘 작동 방식(동일한 hiapi_error 구조가 모든 상태 코드에 적용됨)은 hiapi가 429를 반환하는 이유(및 대처 방법)를 참조하세요.

FAQ

hiapi는 실패한 콜백을 재시도합니까? 엔드포인트가 2xx 응답을 반환할 때만 콜백이 전달된 것으로 간주됩니다. 핸들러가 5xx를 반환하거나, 타임아웃되거나, TLS 핸드셰이크가 실패하면 콜백은 전달되지 않은 것으로 간주하세요. 가장 견고한 패턴은 콜백과 함께 제출한 모든 작업에 대해 항상 GET /v1/tasks/{taskId} 폴링을 폴백으로 사용하는 것입니다. 이렇게 하면 콜백 경로에서 한 번의 장애가 발생해도 결과를 잃지 않습니다.

콜백 URL에 HTTPS 대신 HTTP를 사용할 수 있습니까? 아니요. https://로 시작하는 URL만 허용됩니다. 로컬에서 테스트하는 경우 TLS를 종료하는 터널(Cloudflare Tunnel, ngrok, tailscale funnel)을 사용하고 콜백을 공인 HTTPS 엔드포인트로 지정하세요.

핸들러가 요청 본문을 받았는데 서명 검증이 실패하는 이유는 무엇입니까? (a) 작업을 제출한 후에 Webhook Sign Key를 생성했기 때문입니다—요청이 이전 키(또는 키 없이)로 서명되었습니다—따라서 다시 생성하고, 저장하고, 새 작업을 제출하세요; 또는 (b) 검증 코드가 정규 문자열을 재구성하는 방식이 hiapi와 다르기 때문입니다. 서버가 수신한 요청 본문의 정확한 바이트를 기록하고 해당 바이트에 대해 HMAC을 다시 실행하세요, 중간에 JSON 재직렬화를 수행하지 마세요.

taskId가 success를 표시하지만 콜백도 결과 URL도 받지 못했습니다. GET /v1/tasks/{taskId}를 다시 요청하여 output 배열을 확인하세요. output[*].url의 URL은 시간 제한(expireAt)이 있습니다; 즉시 다운로드하세요. 콜백 전송과 URL 유효성은 별개의 문제입니다—콜백이 없더라도 GET 엔드포인트가 진실의 원천입니다.

/en/dashboard/logs에서 콜백을 보았지만 서버는 기록하지 않았습니다. 이것은 hiapi가 아닌 경계 네트워크의 문제입니다. 일반적인 원인으로는 팀에서 식별 가능한 User-Agent가 없는 POST 요청을 차단하는 CDN/WAF 규칙, 방화벽의 IP 허용 목록, 또는 경로를 재작성하는 역방향 프록시가 있습니다. 방화벽에서 해당 인바운드 POST를 허용한 후 다시 실행하세요.

콜백 URL이 계정 속도 제한을 소모합니까? 아니요. 콜백은 hiapi가 귀하에게 수행하는 전송이며 POST /v1/tasks 속도 예산과 무관합니다.