웹훅(Webhook) 이해하기
웹훅(Webhook) 이해하기
전화가 걸려 오거나 SMS가 도착했을 때, 우리 앱이 그 사실을 어떻게 알 수 있을까요? Twilio REST API가 앱→Twilio 방향의 요청이라면, 그 반대 방향 — Twilio가 우리 앱에 알려주는 채널이 웹훅이에요. 특정 이벤트가 발생하면 Twilio가 우리가 등록해 둔 URL로 HTTP 요청을 보내주는 구조예요. 그래서 우리 앱이 Twilio와 상시 연결을 유지하지 않아도 이벤트를 비동기로 받을 수 있어요.
웹훅이란 무엇인가
Twilio에서 어떤 이벤트가 발생하면, 우리 앱을 위해 Twilio에 등록해 둔 웹훅 URL로 Twilio가 HTTP 요청을 보내요. 이 요청이 곧 웹훅 혹은 콜백이에요. 예를 들어 고객이 Twilio가 제공하는 고객센터 번호로 전화를 걸었다가 끊으면, Twilio가 우리 웹앱에 웹훅을 보내고 우리는 그 통화를 처리한 상담원을 '대기 가능'으로 바꾸거나, 통화 길이를 고객 프로필에 기록하거나, 후속 메모를 쓰게 유도할 수 있어요.
이런 방식은 GitHub·Slack 같은 현대 웹 서비스도 이벤트 전달에 쓰는 패턴이에요. 우리 웹앱이 서비스와 열린 세션이나 연결을 유지하지 않으므로, 서비스가 우리 앱으로 비동기 HTTP 요청을 보내는 거죠.
웹훅의 두 종류
Twilio는 두 가지 유형의 웹훅을 관리해요.
- 제품 기반 웹훅 — 각 제품(Voice, Messaging, Conversations, Sync)이 서로 다른 이벤트를 처리해요. 어떤 웹훅을 쓰고 어떻게 설정하는지는 해당 제품 문서를 참조해요.
- 런타임 웹훅 — 제품 이벤트 외에도 앱에서 발생하는 이벤트(예: 사용량이 임계값에 도달한 경우, 오류 발생)에 대해 Twilio가 웹훅을 보내요. 이걸 Slack·Microsoft Teams 같은 채팅 시스템으로 파이프라인을 만들어 보낼 수도 있어요.
받은 웹훅으로 무엇을 하나
Twilio가 보내는 웹훅은 크게 두 가지 목적이 있어요.
- 지시를 요청하는 웹훅 — 예를 들어 Twilio 번호로 SMS가 도착하면 우리 앱에 웹훅을 보내고, 우리는 유효한 TwiML 문서를 돌려줘서 '이대로 진행하라'는 지시를 전달해요.
- 정보를 알려주는 웹훅 — 음성 녹음이 끝났다는 알림처럼 정보만 전달하는 경우도 있어요. 이때는 수신을 확인하는 응답 외에 특별한 지시를 요구하지 않아요.
웹훅 전달 방식 제어
Webhooks configuration API로 아웃바운드 웹훅이 인증·서명·전달되는 방식을 URL별로 제어할 수 있어요.
- 인증 — OAuth 2.0, Basic, Digest 자격증명으로 Twilio가 우리 엔드포인트에 인증하도록 설정해요.
- 서명 — 계정 인증 토큰 대신 우리가 관리하는 키로 요청에 서명할 수 있어요.
- 타임아웃·재시도·엣지 존 — Twilio가 쓰는 타임아웃, 재시도 횟수, 엣지 존을 설정하고 이를 웹훅 규칙으로 수집할 수 있어요.