OpenAI 웹훅이 두 번 왔다면, 처리는 한 번만 하세요

웹훅 서명 확인과 중복 처리 방지를 설명하는 AI 생성 이미지.

AI 작업 완료 알림을 받아 이메일을 보내는 자동화를 만들었다고 해볼게요. 같은 알림이 다시 오면 메일까지 두 번 나갈 수 있습니다. 알림의 서명 확인과 중복 방지는 따로 필요합니다.

OpenAI API 웹훅을 받는 서버를 이미 만들고 있는 분을 위한 점검 순서입니다. 실제 계정에서 시험한 사용기가 아니라, 2026년 10월 9일 공식 문서를 확인해 정리한 가이드입니다.

1. 받은 본문을 바꾸기 전에 서명을 확인합니다

웹훅은 작업 완료 같은 일이 생겼을 때 내 서버로 보내는 알림입니다. 서버는 먼저 이 요청이 OpenAI에서 온 것인지 확인해야 합니다.

Python SDK의 unwrap()은 서명을 확인하고 본문을 이벤트로 읽어줍니다. Flask를 쓴다면 request.get_data(as_text=True)로 받은 원문과 request.headers를 전달하는 방식입니다. JSON을 먼저 읽어 다시 문자열로 만들면 원문이 달라질 수 있습니다.

서명 확인용 비밀키는 서버의 OPENAI_WEBHOOK_SECRET 환경변수에 보관하세요. API 키와 용도가 다릅니다. 코드나 공개 로그에는 값을 적지 않습니다. 구체적인 연결 코드는 아래 공식 Python SDK 예제를 기준으로 확인하세요.

2. 같은 알림인지 ID를 비교합니다

서명이 맞아도 처음 온 알림이라는 뜻은 아닙니다. 공식 안내에는 드물게 같은 이벤트가 중복 전달될 수 있다고 나옵니다. 수신 서버가 성공 응답을 주지 못해 다시 전달되는 경우도 있습니다.

이때 webhook-id 헤더를 중복 확인에 쓸 수 있습니다. 예를 들어 설명용 ID가 wh_demo_1이라면, 처음 받은 요청은 처리 대상으로 등록하고 같은 ID가 다시 오면 새 이메일 발송을 만들지 않는 식입니다. 실제 수신 기록이 아닌 예시입니다.

단순히 “ID가 없으면 저장”하는 두 동작을 따로 실행하면 동시 요청이 모두 통과할 수 있습니다. 데이터베이스에서 같은 ID를 중복 등록하지 못하게 하고, 등록과 작업 생성이 함께 안전하게 이어지도록 설계해야 합니다. 메모리 목록만으로는 서버 재시작 뒤 기록이 남지 않습니다.

3. 접수와 실제 작업을 나눕니다

OpenAI는 200처럼 접수 성공을 뜻하는 2xx 응답을 빠르게 보내도록 권장합니다. 오래 걸리는 처리는 별도의 작업으로 넘겨 처리할 수 있죠. 다만 작업을 안전하게 저장하기도 전에 성공부터 보내면, 그 뒤 서버가 꺼졌을 때 일을 놓칠 수 있습니다.

권장 흐름은 서명 확인 → 중복 확인과 작업 접수 기록 → 성공 응답 → 실제 작업 처리입니다. 이미 접수된 알림은 새 작업을 만들지 않되, 앞선 작업이 실패했다면 저장된 상태를 보고 다시 처리할 수 있어야 합니다.

이메일 서비스 호출이 성공한 직후 서버가 꺼지는 상황까지 생각하면 더 복잡해집니다. ID 기록 하나만으로 모든 작업이 정확히 한 번 실행된다고 보장할 수는 없습니다. 외부 서비스가 지원하는 중복 방지 기능과 실패 복구도 함께 확인해야 합니다.

4. 테스트에서는 세 가지만 봅니다

운영 메일 발송을 연결하기 전에 테스트 환경에서 정상 알림 한 건, 같은 ID의 재전달, 잘못된 서명을 각각 확인하세요. 목표는 정상 요청 접수, 재전달 시 새 작업 없음, 서명 오류 시 처리 거부입니다.

공식 테스트 이벤트를 받으려면 외부에서 접근 가능한 엔드포인트가 필요합니다. 내 PC의 localhost 주소만 적어두면 도착하지 않습니다. 모형 데이터로 통과한 테스트를 실제 OpenAI 연결 성공으로 보지 마세요.

지금은 로그에서 webhook-id, 서명 확인 결과, 접수·완료 상태를 따로 구분할 수 있는지부터 살펴보세요. 알림 두 건과 실제 작업 두 건을 구분해야 고칠 곳이 보입니다. 비밀키나 전체 요청 내용을 로그에 남기라는 뜻은 아닙니다.

공식 근거: OpenAI 웹훅 가이드와 Python SDK의 Webhook Verification 절. 위 접수·복구 흐름은 공식 전달 조건을 바탕으로 설명한 설계 예시이며, 실제 서비스 테스트 결과가 아닙니다.

Webhooks | OpenAI API

openai-python/README.md at main · openai/openai-python