웹훅(Webhook)이란? sona.to 웹훅 작동 방식

웹훅은 어떤 일이 일어나는 순간 한 앱이 다른 앱에 보내는 메시지로, 받는 쪽이 계속 물어볼 필요가 없게 해 줍니다. 첫 번째 앱에 주소를 알려 주면, 이벤트가 생길 때마다 그 내용을 곧바로 그 주소로 보냅니다. 이 가이드는 웹훅이 작동하는 방식, 웹훅이 진짜인지 확인하는 방법, sona.to가 보내는 내용을 설명합니다. Webhooks 페이지에도 요약되어 있습니다.

웹훅이란?

대부분의 앱은 두 가지 방식으로 데이터를 주고받습니다. API에서는 내 시스템이 "게시물이 게시됐어?"라고 묻고, 아니라는 답이 오면 나중에 다시 묻습니다. 웹훅에서는 앱이 먼저 알려 줍니다. 게시물이 게시되면 내가 고른 주소로 게시물 정보를 담은 요청을 보냅니다.

즉 웹훅은 내가 관리하는 URL로 보내는 HTTP 요청이며, 보통 JSON 본문을 담은 POST입니다. 그 URL은 내 서버일 수도 있고, 요청이 도착하면 워크플로를 시작하는 n8n, Zapier, Make, Slack 같은 서비스가 준 웹훅 주소일 수도 있습니다.

웹훅과 API의 차이

API는 묻고 바꾸기 위한 것입니다. 게시물 목록 보기, 게시물 만들기, 수치 읽기 같은 것입니다. 웹훅은 알림을 받기 위한 것입니다. 대부분의 연동은 둘 다 씁니다. 게시물을 만들 때는 API를, 게시되었는지 실패했는지 알아낼 때는 웹훅을 씁니다. API에 계속 물어보면 요청이 낭비되고 그래도 늦게 알게 되지만, 웹훅은 이벤트가 일어나자마자 도착합니다.

웹훅 검증 방법

웹훅 주소를 아는 사람은 누구나 가짜 요청을 보낼 수 있으므로, 잘 만든 웹훅에는 서명이 있습니다. 보내는 쪽은 본문과 공유 비밀 키로 보통 HMAC SHA-256을 써서 서명을 계산하고 헤더에 넣습니다. 받는 쪽은 같은 비밀 키로 같은 서명을 계산하고, 상수 시간 비교로 둘을 비교합니다. 다르면 요청을 무시합니다.

서명하는 데이터에 타임스탬프를 넣으면 재전송 공격도 막을 수 있습니다. 한 번 가로챈 요청은 타임스탬프가 너무 오래되어 나중에 다시 보낼 수 없습니다.

sona.to의 웹훅

sona.to는 네 가지 이벤트에 웹훅을 보냅니다. 게시물 게시, 게시물 실패, 사이트 진단 완료, 사이트 진단 실패입니다. 웹훅마다 받을 이벤트를 고를 수 있어서, 채팅 알림은 실패만 받고 보고용 시트는 전부 받게 할 수 있습니다. 페이로드는 sona.to API와 같은 필드 이름을 씁니다.

설정하기. 대시보드의 API 페이지에서 주소를 붙여 넣고, 이벤트를 체크하고, 저장합니다. 서명용 비밀 키는 그때 한 번만 표시되므로 바로 복사하세요.

서명. 모든 전송에는 타임스탬프, 그리고 타임스탬프와 본문을 내 비밀 키로 계산한 HMAC SHA-256 값을 담은 헤더가 붙습니다. 타임스탬프가 몇 분 이상 지난 요청은 거부하세요.

재시도. 주소가 다운되었거나 오류를 돌려주면 60초, 5분, 30분 뒤에 다시 전송합니다. 모든 시도는 상태 코드, 소요 시간과 함께 기록됩니다. 계속 실패하는 주소는 비활성화되며, 고친 뒤 다시 켤 수 있습니다.

보안. 주소는 https를 쓰고 공개 서버를 가리켜야 합니다. 사설 네트워크 주소는 저장할 때와 전송할 때 모두 거부되고, 리디렉션은 따라가지 않습니다.

n8n, Zapier, Make의 웹훅

n8n, Zapier, Make용 sona.to 앱에는 같은 네 가지 이벤트용 트리거가 준비되어 있어, 주소를 직접 붙여 넣을 필요가 없습니다. 트리거를 추가하면 앱이 웹훅을 설정합니다. n8n, Zapier, Make로 하는 SNS 자동화를 참고하세요.

서명 확인 예시를 포함한 자세한 내용은 API 문서에 있습니다.

자주 묻는 질문

웹훅은 API와 같은 것인가요?

아니요. API는 물어볼 때 답합니다. 웹훅은 어떤 일이 생기면 메시지를 보냅니다.

sona.to 웹훅은 무료인가요?

웹훅은 API와 함께 모든 요금제에 포함됩니다.

내 서버가 다운되면 어떻게 되나요?

sona.to는 약 30분에 걸쳐 세 번 다시 시도합니다. 전송이 계속 실패하면 내가 다시 켤 때까지 웹훅은 꺼집니다.