AI 에이전트를 위한 회복 탄력성 있는 웹훅 릴레이(Webhook Relay) 구축 방법

문제점

AI 에이전트는 이메일 수신함이 없습니다. 몇 초마다 API를 폴링(poll)하지도 않습니다 (해서도 안 됩니다). 하지만 세상은 여전히 웹훅(webhooks), 콜백(callbacks), 이벤트 스트림(event streams)을 통해 소통합니다. 양식 제출, 결제 확인, 데이터 수집 파이프라인(data ingestion pipelines)과 같이 현실 세계의 이벤트에 반응해야 하는 AI 에이전트를 구축할 때는 이러한 들어오는 신호들을 안정적으로 처리할 수 있는 인프라가 필요합니다.

이것이 바로 AgentForms가 해결하고자 하는 과제, 즉 AI 에이전트를 위한 양식 인프라입니다. 하지만 가장 어려운 부분은 양식 그 자체가 아니라, 세상과 에이전트 사이에 위치하는 **웹훅 릴레이(webhook relay)**였습니다.

왜 릴레이인가?

웹훅 처리에 대한 단순한 접근 방식은 다음과 같습니다:

제3자 API → 귀하의 에이전트 엔드포인트(Endpoint) → 처리

여기에는 다음과 같은 문제들이 있습니다:

에이전트가 항상 온라인 상태인 것은 아닙니다. 컨테이너(Containers)가 재시작됩니다. 배포(Deployments)가 이루어집니다.
제3자의 재시도(retries) 방식은 예측할 수 없습니다. Stripe는 지수 백오프(exponential backoff)를 사용하여 재시도합니다. GitHub은 5번 재시도합니다. 어떤 서비스는 아예 재시도하지 않습니다.
하나의 느린 핸들러가 모든 것을 차단합니다. 웹훅을 처리하는 데 12초가 걸린다면, 엔드포인트는 12초 동안 묶이게 됩니다. 대부분의 웹훅 송신자는 5~10초 후에 타임아웃(timeout)이 발생합니다.
전송 보장(delivery guarantees)이 없습니다. 처리 도중에 에이전트가 충돌(crash)하면 이벤트는 유실됩니다.

릴레이 패턴은 수신과 처리를 분리함으로써 이 모든 문제를 해결합니다:

제3자 API → 릴레이 (즉시 응답(ack)) → 큐(Queue) → 워커(Worker) (자신의 속도에 맞춰 처리)

릴레이 아키텍처

AgentForms는 이를 두 개의 Docker 컨테이너인 **릴레이(relay)**와 **워커(worker)**로 구현합니다. 이들은 Redis를 통해 통신합니다.

릴레이: 빠른 응답(Ack), 빠른 전달

릴레이의 역할은 간단합니다. 웹훅을 수락하고, 검증하고, 저장한 다음, 이상적으로는 100ms 이내에 200 응답을 보내는 것입니다.

다음은 Flask를 사용한 Python 기반의 핵심 릴레이 핸들러입니다:

import hmac
import hashlib
import json
...

여기서의 핵심 설계 결정 사항은 다음과 같습니다:

처리 전 200 응답 (200 before processing). 페이로드(payload)를 건드리기 전에 송신자에게 성공 응답을 보냅니다. 릴레이(relay)는 거의 아무것도 하지 않기 때문에 매우 빠릅니다.
서비스별 검증 (Per-service validation). 각 서비스마다 서로 다른 서명 메커니즘 (signing mechanisms)을 사용합니다. Stripe는 서명과 함께 t= 타임스탬프 (timestamp)를 보내며, GitHub은 SHA256 HMAC을 보냅니다.
24시간 TTL (24-hour TTL). 웹훅 (webhooks)을 무기한 보유하지 않습니다. 만약 워커 (worker)가 24시간 이내에 웹훅을 처리하지 못한다면, 무언가 잘못된 것이며 알림 (alerting)이 필요하다는 신호입니다.

워커 (The Worker): 재시도를 통한 신뢰할 수 있는 처리

워커는 큐 (queue)에서 이벤트를 가져와 처리합니다. 처리에 실패할 경우, 지수 백오프 (exponential backoff)를 사용하여 재시도합니다.

import redis
import json
import time
...

Docker Compose

두 서비스는 Redis를 공유하며 나란히 실행됩니다:

version: '3.8'

services:
...

이것이 AI 에이전트에게 중요한 이유

AI 에이전트는 본질적으로 상태 유지 (stateful) 방식입니다. 에이전트는 컨텍스트 (context)를 유지하고, 대화 스레드 (conversation threads)를 추적하며, 장시간 실행되는 작업 (long-running tasks)을 관리합니다. 웹훅은 외부 세계가 이러한 흐름을 중단시키는 주요 방식입니다. 예를 들어 양식 제출 (form submission)이 도착하거나, 결제가 완료되거나, 데이터 파이프라인 (data pipeline)이 종료되는 경우입니다.

웹훅 처리 방식이 취약하다면, 에이전트 또한 취약해집니다. 웹훅을 놓친다는 것은 이벤트를 놓친다는 것을 의미하며, 이는 일관되지 않은 상태 (inconsistent state)로 이어져 결국 에이전트가 불완전한 정보에 기반하여 결정을 내리게 만듭니다.

릴레이 패턴 (relay pattern)은 다음과 같은 이점을 제공합니다:

결합되지 않은 확장성 (Decoupled scaling). 양식 제출이 급증하는 피크 시간대에는 릴레이를 확장하고, 지속적인 처리량을 유지해야 할 때는 워커를 확장합니다.
결함 격리 (Fault isolation). 워커에서 발생하는 느린 데이터베이스 쿼리 (database query)가 웹훅 송신자의 타임아웃 (timeout)을 유발하지 않습니다.
감사 추적 (Audit trail). 모든 웹훅은 처리 상태와 함께 저장됩니다. 데드 레터 (dead-lettered) 이벤트에 대해 다시 재생 (replay)하거나, 디버깅하거나, 전달할 수 있습니다.
재시도 의미론 (Retry semantics). 일시적인 네트워크 오류는 빠른 재시도를 수행하고, 속도 제한 (rate limits)에는 긴 백오프 (backoffs)를 적용합니다.

343개의 테스트와 그 이상

검증이 없는 아키텍처 (architecture)는 아무런 의미가 없습니다. AgentForms는 릴레이 검증, 워커 처리, 재시도 로직, 그리고 실패 경로를 다루는 343개의 테스트를 보유하고 있습니다. 다음은 대표적인 테스트 예시입니다:

def test_relay_ack_before_processing(self):
    """워커가 처리하기 전에 릴레이(Relay)가 200 응답을 반환해야 합니다."""
    response = self.client.post('/webhook/stripe',
...

더 나아가기 (Going Further)

이것이 AgentForms의 핵심 릴레이 아키텍처(Relay Architecture)입니다. 실제 운영 환경(Production)에서는 메트릭(Metrics, Prometheus), 트레이싱(Tracing, OpenTelemetry), 그리고 적절한 데드 레터 대시보드(Dead-letter dashboard)를 추가하게 될 것입니다. 하지만 릴레이에서의 빠른 승인(Fast ack), 워커(Worker)에서의 신뢰할 수 있는 처리, 그리고 브리지(Bridge)로서의 Redis를 사용하는 근본적인 패턴은 규모(Scale)와 상관없이 동일하게 유지됩니다.

실제 세계의 이벤트(Real-world events)를 처리해야 하는 AI 에이전트를 구축하고 있다면, 릴레이부터 시작하십시오. 그 외의 모든 것은 그 위에 구축됩니다.

더 자세히 알아보려면 https://agentforms.io를 방문하세요.