AI 초보자 QnA
질문
OpenAI API 웹훅 요청이 진짜인지 어떻게 확인하나요?
답변
수신 주소에 POST 요청이 왔다고 바로 믿으면 안 됩니다. OpenAI가 발급한 웹훅 서명 비밀키와 원본 요청 본문·헤더를 함께 검증해야 합니다. 검증에 실패한 요청은 후속 작업을 실행하지 말고 거절하세요.
웹훅 주소를 아는 사람도 직접 요청을 보낼 수 있습니다. 특히 파일 저장이나 알림 발송처럼 서버에서 다음 일을 자동 실행한다면, 이벤트 내용을 읽기 전에 출처부터 확인하는 순서가 필요합니다.
짧게 답하면
프로젝트의 서명 비밀키 보관 → 원본 본문과 헤더 전달 → SDK 서명 검증 → 확인된 이벤트만 처리 순서입니다. 웹훅을 받는 URL과 API 키는 서명 비밀키의 대용품이 아닙니다.
서명 비밀키
웹훅 엔드포인트를 만들 때 발급됩니다. 서버에서만 보관하고 공개 코드나 글에 넣지 않습니다.
원본 요청
수신한 본문을 다시 JSON으로 조립하지 않고 원래 받은 데이터와 헤더를 검증 함수에 넘깁니다.
검증 후 처리
서명이 유효한 경우에만 이벤트 종류를 확인하고 필요한 작업을 진행합니다.
처음 쓰는 사람 기준으로 설명하면
OpenAI 웹훅은 설정한 프로젝트의 이벤트가 발생하면 등록한 HTTPS 주소로 알림을 보냅니다. 요청에는
webhook-id
,
webhook-timestamp
,
webhook-signature
헤더가 함께 옵니다. 헤더가 있다는 사실만으로 진짜 요청이라고 판단할 수는 없습니다.
엔드포인트를 생성하면 서명 비밀키가 반환됩니다. 공식 API 문서는 새로 만들거나 비밀키를 교체할 때만 그 값을 다시 받을 수 있다고 안내합니다. 분실을 대비해 서버의 비밀 관리 수단에 보관하고, 작업자에게는 값 자체가 아니라 안전한 설정 경로를 알려 주세요.
공식 Python 예제는 환경변수의 비밀키를 SDK에 지정하고
client.webhooks.unwrap(request.data, request.headers)
로 검증과 이벤트 해석을 함께 합니다. 서명이 잘못되면 오류를 받아 거절합니다. 본문을 먼저 파싱해 다시 직렬화하면 원본 데이터가 달라질 수 있으니 수신한 그대로 넘기는 편이 안전합니다.
한 줄 정리: 웹훅 수신은 알림을 받았다는 뜻이고, 서명 검증은 그 알림의 발신 근거를 확인하는 별도 절차입니다.
바로 따라 해보기
1단계. 프로젝트의 엔드포인트를 확인합니다.
OpenAI 대시보드에서 해당 프로젝트의 웹훅을 열어 HTTPS 주소와 구독한 이벤트 종류를 살핍니다. 새 엔드포인트를 만들었다면 표시되는 서명 비밀키를 서버의 비밀 설정에 저장하세요.
2단계. 수신 코드에서 서명을 검사합니다.
예제처럼 서버에 서명 비밀키를 설정하고 원본 요청 본문·헤더를 SDK의
unwrap
에 전달합니다. 검증 오류에는 성공 응답을 보내지 않고, 확인된 이벤트 종류에 대해서만 후속 작업을 시작합니다.
3단계. 시험 전송과 중복을 점검합니다.
공식 Test Webhook Endpoint 기능으로 표본 이벤트를 보내 수신 서버가 돌려준 상태 코드를 확인하세요. 같은 이벤트가 다시 오면
webhook-id
를 기준으로 중복 실행을 막고, 실제 결과 ID도 필요한 경우 조회합니다.
주의할 점
서명 검증만 하고 서버 응답이나 중복 처리를 놓치면 작업이 두 번 실행될 수 있습니다. 검증된 요청에는 빨리 성공 상태를 돌려주고 오래 걸리는 작업은 따로 처리하세요. 비밀키가 노출되거나 분실됐다면 교체하고 서버의 저장값도 새 키로 바꿔야 합니다.
요청 본문을 다시 조립해 검증하거나, 헤더 이름만 확인하고 서명이 맞는지 검사하지 않습니다.
검증 오류에도 파일 저장이나 메시지 전송을 진행합니다. 실패 요청은 성공 처리와 분리하세요.
시험 전송 결과의 success만 보고 실제 수신 서버의 상태 코드를 확인하지 않거나, 중복 전송을 한 번만 올 것으로 가정합니다.
웹사이트와 앱 중 무엇부터 쓰면 좋을까요?
웹사이트에서 확인할 때
대시보드에서 프로젝트·웹훅 주소·구독 이벤트를 먼저 확인하세요. 시험 전송은 실제로 접근 가능한 서버 주소를 준비한 뒤 진행합니다. 비밀키는 화면에서 복사하더라도 공유 채팅에 붙여 넣지 마세요.
앱이나 서버 코드에서 처리할 때
웹 채팅 앱에 웹훅 서명 검증 버튼이 있는 것은 아닙니다. 웹훅을 받는 내 서버 코드에서 원본 요청과 비밀키를 검사하세요. 테스트가 통과해도 실제 자동 작업의 중복 실행 여부는 별도로 확인합니다.
확인한 공식 자료
OpenAI API Docs — Webhooks — 원본 본문과 헤더의 서명 검증, 빠른 응답과 중복 처리 기준을 확인했습니다.
OpenAI API Reference — Create Webhook Endpoint — HTTPS 수신 URL·구독 이벤트·서명 비밀키 반환 조건을 확인했습니다.
OpenAI API Reference — Test Webhook Endpoint — 표본 이벤트 전송과 응답 상태 코드 확인 방법을 확인했습니다.
OpenAI API Docs — Background mode — 긴 응답을 백그라운드에서 실행하고 결과 상태를 별도로 조회하는 맥락을 확인했습니다.
감자나라 AI 강의보기 5,000 
