Slack Events API 안정화 가이드: 3초 ACK·큐·실패 복구

한 줄 요약

Slack Events API는 요청 검증과 접수 기록만 동기 처리하고 3초 안에 ACK한 뒤, 실제 작업은 멱등성을 갖춘 비동기 큐와 worker에서 처리해야 한다.

Slack 이벤트가 중복 처리되거나 긴 작업 중 타임아웃이 발생한다면 봇 역할보다 이벤트 수신 경계를 먼저 점검해야 한다. 이 글은 HTTP Events API 기준으로 서명 검증 → 3초 ACK → 영속 큐 → worker → 결과 확인 경로를 안정화하는 방법을 다룬다. Socket Mode를 선택했을 때 달라지는 운영 지점도 함께 정리한다.

앞서 쓴 Slack 봇 기반 업무 자동화 프로세스 구축기는 8개 역할과 단일 관문을 운영한 사례다. 이 글은 그중 이벤트 수신과 실패 복구만 분리한 구현 가이드다. 조직 설계나 자동화 효과보다 ACK 지연, 중복 이벤트, 재시도와 작업 유실을 막는 데 초점을 맞춘다.

여러 요청 카드가 하나의 접수 게이트로 모이고 검증된 작업 폴더로 정리되는 단일 접수 구조

Slack 이벤트 처리 경로는 어떻게 분리해야 하나?

이벤트 수신 서버와 실제 작업 실행기를 한 프로세스로 묶지 않는다. 처리 경로를 먼저 한 줄로 고정한다.

이벤트 수신 → 서명 검증 → 접수 기록 → ACK → 큐 적재 → worker 실행 → 결과 검증 → 같은 스레드 보고

수신기는 원문 검증, 이벤트 식별자 기록, 빠른 큐 전달까지만 담당한다. 문서 생성이나 외부 API 호출은 worker 책임이다. 시작용 상태는 received → queued → working → review → done이면 충분하다. 승인 대기와 실패를 구분해야 한다면 waiting_approval, failed, cancelled, stale을 추가한다.

여러 책상과 채널에 흩어진 요청이 단일 퍼널과 작업 큐로 정리되는 전후 비교

최소 구성은 이벤트 수신기, 영속 작업 큐, worker, 상태 저장소다. ACK 전에 긴 작업을 시작하지 않고, event_id 또는 별도 업무 키를 상태 저장소에 기록해 같은 이벤트가 다시 와도 한 번만 실행되게 한다.

접수, 라우팅, 작업, 검수, 결과 저장, 같은 스레드 회신으로 이어지는 여섯 단계 업무 흐름

Slack 이벤트를 왜 3초 안에 ACK해야 하나?

Slack HTTP Events API는 이벤트를 받은 뒤 3초 안에 응답해야 한다. 문서 생성이나 외부 API 호출을 요청 처리 안에서 끝내려 하지 말고, 서명과 최소 입력을 확인한 뒤 업무 키를 영속 저장소에 기록하고 ACK한다. 긴 작업은 별도 worker가 처리하고 진행 상태는 같은 스레드에 갱신한다.

큐가 느릴 때 ACK까지 함께 지연되지 않도록 수신 경로에는 짧고 내구성 있는 inbox 기록만 둔다. ACK를 먼저 보내고 메모리에만 작업을 남기면 프로세스가 종료될 때 이벤트를 잃을 수 있으므로, ACK 속도와 유실 방지를 함께 만족해야 한다.

공개 Request URL을 운영하기 어렵다면 Socket Mode로 WebSocket 연결을 사용할 수 있다. HTTP 수신과 Socket Mode는 같은 이벤트를 다루지만 인증, 연결 유지, 장애 감시 방식이 다르므로 하나의 수신 경로처럼 섞지 않는다.

app_mention 수신에는 app_mentions:read, 메시지 전송에는 chat:write가 필요하다. DM의 message.im을 구독한다면 im:history가 필요하다. 필요한 이벤트와 기능을 먼저 정한 뒤 최소 scope만 부여한다.

요청은 자유 문장으로만 남기지 않고 아래 다섯 항목으로 구조화한다.

[업무 요청]
목적:
산출물:
완료 조건:
기한:
주의 사항:

목적, 산출물, 완료 조건, 기한, 주의 사항을 상징하는 다섯 개 요청 계약 카드

큐 메시지와 작업 상태는 어떻게 설계하나?

큐 메시지에는 업무 키, Slack 이벤트 식별자, workspace와 channel, 원본 thread_ts, 요청자, 작업 유형, 완료 조건을 넣는다. 라우터는 이 메시지를 보고 1차 worker 하나를 선택한다. 같은 일을 여러 worker에 복제하지 않고, 추가 역할이 필요하면 별도 하위 작업 키를 발급한다.

중앙 라우터가 하나의 작업 카드를 주 담당 역할에 보내고 두 지원 역할을 연결하는 구조

worker 응답도 role, decision, findings, risks, next_action처럼 공통 형식으로 맞추면 다음 단계가 사람의 문장 해석에 의존하지 않는다. 상태 저장소에는 업무 키, 현재 상태, 시도 횟수, 마지막 오류, 다음 재시도 시각, 결과 위치처럼 재개에 필요한 정보만 남긴다. 원문과 민감 정보의 보존 기간도 상태 모델에 포함한다.

진행 대화와 지속 상태 보관판을 분리하고 민감한 조각을 제거한 최소 정보만 저장하는 구조

worker 완료는 어떤 기준으로 확정하나?

큐에서 메시지를 꺼냈거나 외부 API가 200을 반환했다는 사실만으로 done을 기록하지 않는다. 파일을 만들었다면 다시 열어 내용과 위치를 확인하고, 외부 시스템을 바꿨다면 사용자가 보는 표면에서 결과를 재조회한다. 완료 기록은 대상 / 기대값 / 실제값 / 판정 / 근거 형식으로 남긴다.

결과 확인, 품질 검사, 수정, 재검수 네 단계가 순환하고 승인에서 종료되는 품질 게이트

검수에 실패하면 반려 이유를 상태에 기록하고 같은 기준으로 재검사한다. 완료 보고에는 실행했다는 말보다 무엇을 어디에서 다시 읽어 확인했는지를 적는다. 이 read-back이 있어야 요청 수락과 실제 결과 완성을 구분할 수 있다.

왼쪽의 요청 수락 신호와 오른쪽의 개봉, 기어 작동, 확대경 검수, 승인 씰을 대비한 read-back 설명

이벤트 처리가 멈췄을 때 어디부터 진단해야 하나?

여러 worker가 동시에 멈춘 것처럼 보여도 원인이 각 worker에 있는 것은 아닐 수 있다. 이벤트 유입 → 라우터 연결 → 큐 적재 → worker 소비 → 결과 전송 순서로 공통 경로부터 좁힌다. 단일 접수 구조는 운영을 단순하게 만들지만 중앙 라우터가 단일 실패 지점이 될 수 있다.

입력 카드와 큐, 정상 worker 세 개 사이에서 중앙 라우터의 끊어진 연결을 먼저 조사하는 장애 진단

Slack은 이벤트 전달에 실패하면 재시도할 수 있다. event ID나 업무 키로 중복 실행을 막고, 429 응답에는 Retry-After만큼 기다린다. 라우터는 재접속을 준비하고 stale 작업은 자동 재개 가능한 작업과 사람 확인이 필요한 작업으로 나눈다.

ACK 전에 어떤 요청 검증이 필요한가?

빠른 ACK가 검증 생략을 뜻하지는 않는다. HTTP 요청은 X-Slack-Request-Timestamp가 현재 시각과 5분 넘게 차이나면 거부하고, 파싱 전 원문으로 서명을 계산해 상수 시간으로 비교한다. 검증을 통과하지 못한 요청은 큐에 넣지 않는다.

토큰은 코드, 로그, 프롬프트에 넣지 않고 secret 저장소에서 주입한다. 노출됐다면 화면에서 지우는 데 그치지 않고 먼저 폐기·회전한 뒤 메시지와 로그에 남은 값을 정리한다. 앱 scope와 요청자 권한은 별개이므로 서버에서 허용 workspace, channel, user와 작업 종류도 검사한다.

AI worker는 메시지와 링크를 신뢰된 명령으로 간주하지 않는다. 호출 가능한 도구와 외부 도메인을 allowlist로 제한하고 실행 전 정책 검사를 둔다.

비밀값 금고, 요청자 확인, AI 입력 필터, 사람 승인 네 체크포인트가 자동화 경계를 이루는 구조

자동 재시도와 사람 승인 경계는 어디에 두나?

읽기 전용 작업이나 멱등 키로 중복 부수 효과를 막을 수 있는 작업은 지수 백오프와 최대 시도 횟수를 정해 자동 재시도한다. 외부 발행, 삭제, 결제, 권한 변경처럼 되돌리기 어려운 작업은 재시도 전에 사람이 승인한다. 고위험 승인은 업무 키, 대상, 만료 시각에 묶어 이전 요청에 재사용되지 않게 한다.

완성된 글과 이미지 패키지를 검토한 소유자가 발행 직전 승인 버튼에 손을 올린 장면

배포 전 점검표

Slack 원문 기준 요청 서명과 타임스탬프를 검증하는가?
이벤트 식별자나 업무 키로 중복 실행을 차단하는가?
ACK 지연과 큐 적재 실패를 서로 다른 지표로 감시하는가?
429 응답의 Retry-After와 최대 재시도 횟수를 지키는가?
failed, stale, waiting_approval 상태에서 재개할 담당자가 정해져 있는가?
완료 결과를 재조회하고 원래 Slack 스레드에 근거를 남기는가?
비밀값 회전과 고위험 작업의 사람 승인 경로가 준비되어 있는가?

자주 묻는 질문

ACK 뒤 실제 작업이 실패하면 어떻게 알리나?

접수 직후 같은 스레드에 업무 키와 queued 상태를 남긴다. 실패하면 원인, 재시도 여부, 필요한 사람 조치를 같은 스레드에 갱신한다. 실패를 성공 메시지로 덮지 않는다.

Socket Mode와 HTTP Events API 중 무엇을 선택해야 하나?

공개 엔드포인트 운영이 어렵다면 Socket Mode가 편하다. 다만 공개 Slack Marketplace 앱에는 사용할 수 없다. Socket Mode는 WebSocket 재연결을, HTTP 방식은 엔드포인트 가용성과 응답 지연을 감시한다.

stale 작업은 자동으로 다시 시작해도 되나?

읽기 전용이거나, 영속 저장소에서 업무 키를 원자적으로 선점하고 부수 효과를 멱등 처리할 수 있을 때만 자동 재개한다. 외부 발행, 삭제, 결제는 사람이 확인한다.

한계와 업데이트 예정

이 글은 Slack 앱의 전체 구현 코드를 제공하는 튜토리얼이 아니라 Events API 수신, 큐 전달, 실패 복구 경계를 설계하는 가이드다. 역할을 나눈 운영 방식과 실제 사고 기록은 별도의 구축기에서 다룬다. 실제 scope와 rate limit, Socket Mode 정책은 앱 유형과 Slack 정책 변경에 따라 달라질 수 있다.

이후에는 멱등성 키 저장 방식과 dead-letter queue, 승인 만료 정책을 코드 예시와 함께 분리해 다룰 예정이다.

이 글은 AI 업무 자동화 허브의 ‘실행·안정화’ 단계 사례다.

공식 문서

확인일은 2026년 7월 11일이다. 실제 구축 전에는 공식 문서의 최신 정책을 다시 확인해야 한다.