[OpenAI][API] Responses API background mode와 webhook을 같이 쓸 때 놓치기 쉬운 점

IT 리서치 노트

[OpenAI][API] Responses API background mode와 webhook을 같이 쓸 때 놓치기 쉬운 점

Responses API에서 background mode를 켜면 응답을 기다리는 방식이 바뀐다. 요청 직후 결과를 바로 받는 흐름이 아니라 작업 상태를 추적하고, 완료 신호를 어디서 받을지 설계해야 한다. 실무에서는 background mode만 켜고 webhook 검증을 빼먹거나, polling과 webhook을 동시에 붙여 중복 저장을 만드는 경우가 많다. 이 글은 요청 생성, 상태 확인, webhook 검증, 재시도 분리까지 한 번에 정리한다.

목차

1. 개요
2. 어디서 막히는가
3. 실제로 해결하는 순서
4. 화면과 출력으로 확인하기
5. 주의할 점
6. 결론
7. 참고 링크

1. 개요

Responses API에서 background mode를 켜면 응답을 기다리는 방식이 바뀐다. 요청 직후 결과를 바로 받는 흐름이 아니라 작업 상태를 추적하고, 완료 신호를 어디서 받을지 설계해야 한다.

실무에서는 background mode만 켜고 webhook 검증을 빼먹거나, polling과 webhook을 동시에 붙여 중복 저장을 만드는 경우가 많다. 이 글은 요청 생성, 상태 확인, webhook 검증, 재시도 분리까지 한 번에 정리한다.

• 이 글은 현재 공식 문서와 공개 도움말을 다시 확인한 뒤 정리했다.
• 설정 경로, 실패 지점, 검증 결과를 분리해서 읽으면 바로 실행에 옮기기 쉽다.
• 실제 운영에서는 권한, 비용, 배포 로그를 함께 봐야 같은 실수를 반복하지 않는다.

2. 어디서 막히는가

문제가 길게 보이더라도 실제 막힘은 몇 가지 패턴으로 모인다. 아래 증상 중 하나라도 보이면 설정값, 요청값, 실행 결과를 분리해서 기록하는 쪽이 빠르다.

• HTTP 요청은 200으로 끝났는데 실제 생성 결과는 몇 초 뒤에야 도착한다.
• webhook은 왔지만 서명 검증을 하지 않아 임의 호출과 구분하지 못한다.
• polling 결과와 webhook 결과를 둘 다 저장해 같은 작업이 두 번 반영된다.
• background 작업이 실패했을 때 어느 응답 ID를 다시 조회해야 하는지 로그에서 바로 찾지 못한다.

여기서 가장 흔한 실수는 증상만 보고 권한을 넓히거나 비용 플랜을 올리거나, 별도 로그 없이 다시 시도하는 것이다. 그러면 당장은 지나가도 다음 배포나 다음 운영 시간대에 같은 문제가 다시 나온다.

따라서 먼저 실제 값과 공식 기준이 어떻게 다른지 좁히고, 그 다음에 클릭, 입력, 실행, 저장 순서를 하나씩 재현해야 한다. 이 순서가 있어야 팀원끼리 같은 결과를 볼 수 있다.

문제정의 단계에서는 오류 문구 한 줄만 보는 대신, 어떤 메뉴에서 확인했고 어떤 필드가 비어 있었는지, 어떤 응답 상태가 먼저 나타났는지까지 적어두는 편이 좋다. 그래야 해결 단계에서 값을 바꾼 뒤에도 같은 기준으로 성공과 실패를 다시 비교할 수 있다.

특히 비용 문제나 권한 문제는 겉으로는 비슷하게 보여도 원인이 다르다. 청구 화면, 콘솔 설정, 배포 로그, 브라우저 요청, CLI 출력 가운데 무엇이 기준 화면인지 먼저 정하고 그 화면을 중심으로 확인해야 엉뚱한 메뉴를 오래 헤매지 않는다.

3. 실제로 해결하는 순서

아래 순서는 메뉴를 열고 값을 확인하고 결과를 다시 보는 실무용 순서다. 한 번에 모두 바꾸지 말고 한 단계씩 적용한 뒤 출력과 화면을 확인하는 편이 안전하다.

1. 먼저 create 응답에서 response id와 status를 저장한다.
2. 다음으로 webhook endpoint에서 서명 검증을 통과한 이벤트만 처리한다.
3. 이어서 polling은 보조 경로로만 두고, 같은 response id는 idempotency 키로 한 번만 반영한다.
4. 마지막으로 timeout, failed, expired 상태를 운영 로그에 분리해서 남긴다.

안전한 예제 코드

import express from "express";

const app = express();
app.post("/webhooks/openai", express.text({ type: "*/*" }), async (req, res) => {
  const signature = req.header("webhook-signature");
  const body = req.body;

  // 실제 검증 함수에는 서버 비밀값을 환경변수로 주입한다.
  const verified = verifyWebhook({
    rawBody: body,
    signature,
    secret: process.env.OPENAI_WEBHOOK_SECRET || "YOUR_WEBHOOK_SECRET",
  });

  if (!verified) return res.status(401).send("invalid signature");

  const event = JSON.parse(body);
  await saveResultOnce(event.data.id, event.type, event.data.status);
  return res.status(200).send("ok");
});

예제의 핵심은 서명 검증과 중복 반영 차단이다. webhook 비밀값, 실제 response id, 내부 콜백 URL은 코드와 로그에 직접 남기지 않는다.

예제 코드는 흐름만 남겼다. 실제 토큰, 계정, 내부 서버 주소, 비공개 저장소 이름은 placeholder로 바꾸고 서버 환경변수나 보안 저장소로 분리한다.

중요한 점은 설정 변경 직후 바로 다음 단계로 넘어가지 않는 것이다. 각 단계마다 어떤 메뉴를 클릭했고, 어떤 값을 입력했고, 어떤 출력이 돌아왔는지 짧게라도 기록해야 한다. 그래야 실패했을 때 마지막으로 바뀐 값이 무엇인지 빠르게 되짚을 수 있다.

또한 해결 절차는 한 번 성공했다고 끝나지 않는다. 같은 절차를 다른 환경이나 다른 브랜치, 다른 계정에서도 다시 실행해 보고 결과가 같은지 확인해야 한다. 운영 환경과 로컬 환경의 URL, 권한, 캐시, 플랜, 리전 차이가 숨어 있으면 여기서 드러나는 경우가 많다.

4. 공식 문서 화면으로 확인할 기준

아래 화면에서는 background mode, webhook, Responses API 전환 문서를 같은 흐름으로 확인한다. 오래 걸리는 작업을 비동기로 처리할 때는 요청 생성, 상태 조회, 이벤트 수신, 서명 검증을 따로 봐야 한다.

먼저 background mode 문서의 시작 화면을 본다. 응답을 바로 기다리지 않는 작업인지, 나중에 상태를 조회해야 하는 작업인지 여기서 기준을 잡는다.

Background mode 문서에서는 장시간 실행 작업을 비동기로 만들고 나중에 결과를 확인하는 흐름을 먼저 확인한다.

그다음 같은 문서 안에서 작업 생성 이후의 처리 방식을 확인한다. 운영 코드에서는 요청을 보낸 뒤 완료 상태를 기다리는 부분과 사용자에게 중간 상태를 보여주는 부분이 분리된다.

background 작업은 요청 생성과 결과 확인 시점이 분리되므로, 화면에 보이는 실행 흐름을 기준으로 상태 처리를 설계한다.

webhook 문서는 백그라운드 작업 완료를 서버가 어떻게 받을지 판단할 때 본다. 단순 polling으로 충분한지, 이벤트 수신 엔드포인트가 필요한지 여기서 나뉜다.

Webhooks 문서에서는 이벤트를 받을 서버 엔드포인트와 처리 흐름을 먼저 확인한다.

운영 환경에서는 webhook을 받는 것보다 검증이 더 중요하다. 서명 검증 위치를 확인하지 않으면 외부 요청을 정상 이벤트로 처리할 위험이 있다.

서명 검증 설명은 webhook 수신 코드에서 반드시 먼저 적용해야 할 보안 기준이다.

마지막으로 Responses API 전환 문서를 함께 본다. 기존 Chat Completions 흐름에서 background mode와 webhook을 붙일 때 어떤 구조가 달라지는지 비교해야 한다.

Responses API 전환 화면에서는 기존 Chat Completions 방식과 새 응답 구조의 차이를 비교한다.

이 순서로 확인하면 문서의 기능 설명, 설정 범위, 제한 조건, 실제 운영 판단 기준을 한 번에 대조할 수 있다. 화면에서 먼저 볼 항목을 정한 뒤 코드나 콘솔 설정을 수정해야 같은 문제가 반복되지 않는다.

5. 주의할 점

설정을 맞췄더라도 운영에서는 다시 틀어지는 지점이 있다. 아래 항목은 배포 직전과 배포 직후에 꼭 다시 점검할 부분이다.

• webhook 재전송을 고려하지 않으면 같은 작업이 다시 저장될 수 있다.
• raw body 대신 파싱된 JSON으로 검증하면 서명 검증이 실패할 수 있다.
• 비동기 처리 흐름을 붙였는데 response id를 저장하지 않으면 장애 추적이 어려워진다.

특히 권한, 비용, 캐시, 재시도 정책은 한 번 맞춘 뒤에도 환경이 바뀌면 다시 확인해야 한다. 문서가 바뀌었는지, 콘솔 기본값이 달라졌는지, 팀의 배포 방식이 바뀌었는지도 같이 본다.

6. 결론

응답 시간이 길어질 수 있으면 background mode를 쓴다.

• 응답 시간이 길어질 수 있으면 background mode를 쓴다.
• 외부 시스템 저장이 걸려 있으면 webhook 서명 검증을 먼저 붙인다.
• 운영상 중복 반영이 치명적이면 polling을 주 경로로 두지 않는다.

핵심은 추상적인 '좋은 설정'을 찾는 것이 아니라, 지금 내 서비스에서 어떤 값과 어떤 출력이 정답인지 빠르게 확인하는 것이다. 이 글의 순서대로 문서, 설정, 실행 결과를 묶어 보면 같은 문제를 다시 만났을 때 훨씬 빨리 끝낼 수 있다.

background 완료 이벤트를 받은 뒤 실제 저장 순서를 더 좁혀 보고 싶다면, 새 후속 글인 response.completed webhook 뒤 retrieve(resp.id) 재조회와 자체 감사 로그를 어떤 순서로 나누는지 정리한 글로 이어서 보면 response id 재조회, idempotency, 감사 로그 분리를 운영 기준으로 바로 연결하기 좋다.

7. 참고 링크

1. https://platform.openai.com/docs/guides/background
2. https://platform.openai.com/docs/guides/webhooks
3. https://platform.openai.com/docs/guides/responses-vs-chat-completions