Event Webhook 개요

Event Webhook 개요

이메일을 보내는 건 완성된 이메일 프로그램의 절반일 뿐이에요. 메시지가 실제로 수신자의 수신함에 도착했는지, 반송(bounce)됐는지, 열어보고 링크를 클릭했는지도 알아야 해요. SendGrid의 Event Webhook은 발송 과정에서 생기는 이벤트 데이터를 거의 실시간으로 내가 지정한 URL에 POST로 보내줘요. 여기선 웹훅 패턴 자체와 Event Webhook의 설정·운영 방법을 정리할게요.

출처: Twilio SendGrid Event Webhook Overview

웹훅이란

웹훅(webhook)은 매번 데이터를 요청하지 않고, 이벤트가 발생할 때 서버가 내가 제공한 URL로 데이터를 보내주는 디자인 패턴이에요. 반대는 폴링(polling)인데, SendGrid가 GET 엔드포인트를 제공해서 새 이벤트 데이터가 있는지 주기적으로 물어보는 방식이에요. 하지만 이러면 새 데이터가 없을 때도 계속 요청해야 해서 부담스러워요.

웹훅에선 내가 원할 때 요청하는 게 아니라, 보낼 데이터가 생기면 SendGrid가 내 URL로 POST 요청을 보내요. 예를 들어 누군가 메시지를 열면 SendGrid가 그 이벤트 데이터를 실어 보내는 식이에요. SendGrid의 Event Webhook은 이렇게 POST 요청을 받을 URL(Post URL)을 하나 제공하면 동작해요.

여기서 용어를 정리하면, 이 페이지에서 말하는 "Event Webhook"은 SendGrid가 내 URL로 POST 요청을 보내는 동작이고, "webhook"은 그 일반적인 패턴을 뜻해요. 데이터를 보낼 목적지 URL은 "Post URL", "endpoint", "destination"이라고 불러요. 요금제에 따라 엔드포인트를 여러 개 둘 수도 있는데, 그러면 서로 다른 이벤트를 다른 목적지로 보내거나 같은 이벤트를 여러 곳에 보낼 수 있어요.

Event Webhook의 쓰임

Event Webhook은 발송과 동시에 이벤트 데이터를 전달하므로 거의 실시간으로 이벤트를 받을 수 있어요. 그래서 로깅·모니터링 시스템과 붙이기 좋아요. 또한 데이터를 내 인프라에 저장해 두고 싶은 경우, 자체 보존·접근 요구를 충족하는 백업/저장 용도로도 잘 맞아요.

SendGrid가 기본 제공하는 Email Activity Feed는 이벤트를 최대 30일만 보관해요. 그 시간이 지나면 이벤트 데이터는 사라져요. SendGrid가 보관해 주는 것보다 더 많은 이벤트 데이터를 쌓고 싶다면 Event Webhook을 설정해야 해요.

이벤트 유형

Event Webhook이 주는 이벤트는 크게 두 부류로 나눠요.

  • 전달성 이벤트 — delivered(도착), bounced(반송), processed(처리) 같은 것. 이메일이 수신자에게 실제로 배달되고 있는지 알려줘요.
  • 참여 이벤트(engagement) — open(열람), click(클릭) 같은 것. 수신자가 이메일을 읽고 상호작용하는지 알려줘요.

두 부류 모두 이메일 프로그램의 전반적인 건강 상태를 파악하는 데 중요하니 함께 모니터링해야 해요. 각 이벤트 유형의 상세는 Event Webhook Reference에서 확인할 수 있어요.

웹훅 추가·설정

웹훅을 새로 만들려면 Getting Started with the Event Webhook 문서를 따라가면 돼요. 추가하거나 수정할 때 다루는 설정은 이래요.

  • Enabled — 웹훅 활성/비활성 토글.
  • Friendly Name — 웹훅을 구분하기 위한 선택적 이름.
  • Post URL — SendGrid가 데이터를 보낼 URL. 내 서버의 엔드포인트, 서드파티 데이터 도구가 주는 엔드포인트, 또는 ngrok 같은 테스트 URL일 수 있어요. 이 URL은 Twilio SendGrid의 POST 요청을 받을 수 있어야 해요.
  • Actions to be posted — 각 웹훅 요청 페이로드에서 받고 싶은 이벤트 유형.
  • 보안 기능(Security features) — Signature Verification 또는 OAuth Verification 중 하나(또는 둘 다)로 POST 요청이 진짜 SendGrid에서 왔는지 검증할 수 있어요.
  • Test Your Integration — 예시 이벤트가 담긴 JSON 배열을 지정한 Post URL로 HTTP POST 요청을 보내는 기능. 테스트 요청은 예시 이벤트로만 이루어지고 실제 발송 데이터는 포함되지 않아요.

편집

SendGrid UI에서 Settings > Mail Settings로 간 뒤, Webhook Settings 아래 Event Webhooks를 열면 등록된 웹훅 목록이 나와요. 엔드포인트 URL 옆의 톱니(설정) 아이콘에서 Edit를 눌러 Post URL 등 필드를 바꾸거나 Delete로 삭제할 수 있어요. 비활성(disable)은 삭제가 아니에요 — 데이터 전송만 막을 뿐 웹훅은 남아 있고, 요금제의 최대 웹훅 개수에는 여전히 집계돼요. API로 관리하고 싶다면 SendGrid Webhooks API를 쓰면 돼요.

삭제

웹훅 삭제는 되돌릴 수 없는 영구 동작이에요. 데이터 수신만 멈추고 싶다면 삭제 대신 비활성화하세요.

계정 다운그레이드와 비활성 웹훅

계정에서 가질 수 있는 웹훅 수는 요금제에 따라 달라져요. 다운그레이드로 현재 개수를 지원하지 않는 요금제가 되면, 가장 최근에 만든 웹훅부터 자동으로 비활성돼요. 예를 들어 웹훅이 5개인데 2개만 허용하는 요금제로 내리면, 최근 만든 3개(created date 기준 최신)가 자동 비활성돼요.

운영 시 알아둘 점

  • Post URL은 리다이렉트를 따르지 않아요. 암호화된 POST를 받으려면 콜백 URL이 TLS 1.2를 지원해야 해요.
  • 웹 서버가 SendGrid에 2xx 응답을 돌려줘야 해요. 다른 응답이면 SendGrid가 2xx를 받거나 최대 시간이 지날 때까지 POST를 재시도해요. 이벤트는 발생 후 최대 24시간까지 간격을 늘려가며 재시도돼요.
  • SendGrid의 IP 주소를 차단하지 마세요. IP는 계속 바뀌어요.
  • 중복 이벤트가 올 수 있어요. 처리·저장할 때는 sg_event_id로 중복 제거(dedup)하는 걸 권장해요. sg_event_id는 최대 100자의 문자열로 Base64url 인코딩되며, 포함된 모든 이벤트에서 유일해요.
  • curl로 Post URL을 직접 테스트할 수도 있어요. 예를 들어 POST 요청에 Content-Type: application/json 헤더와 예시 이벤트 JSON 배열을 담아 보내 내 서버가 뭘 돌려주는지 확인하면 돼요.

더 알아보기