웹훅: 일어난 일을 다른 도구에 알리기

#웹훅이란

프로젝트가 다른 서비스에 전화를 걸어 방금 일어난 일을 알려 주는 것이라고 생각하세요. 다른 도구에서 받은 주소(URL)를 Briks에 알려 주고, 알림을 받을 이벤트를 고르면, 이벤트가 일어날 때마다 Briks가 그 주소로 메시지를 보내요. 많은 자동화 도구, 고객 목록 도구, 스프레드시트 애드온에서 이런 주소를 받을 수 있어요.

기술적으로 각 메시지는 POST 요청이에요. 본문을 담아 보내는 호출로, 여기서는 프로그램이 읽는 일반 텍스트 형식인 JSON으로 작성돼요. 받는 도구가 본문을 읽고 설정해 둔 대로 동작해요.

record.changed는 스튜디오에서 일어난 변경을 따라가요. Database 탭에서 레코드를 추가, 수정, 삭제하거나, 컬렉션을 비우거나, 데이터베이스를 복원하는 경우예요. 방문자가 보낸 예약 요청처럼 라이브 사이트가 스스로 저장하는 레코드는 이 이벤트를 일으키지 않아요.

form.received는 프로덕션뿐 아니라 미리보기에서 들어온 제출 내용에도 전송돼요. 메시지마다 어느 쪽인지 표시되므로, 상대 도구가 미리보기 제출 내용을 건너뛸 수 있어요.

#요금제별 한도

그날의 호출을 모두 쓰면 전송이 이루어지지 않고 Failed로 표시되며 이런 메시지가 나와요: Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.

프로젝트의 웹훅이 플랜이 허용하는 수만큼 되면 Add webhook이 회색으로 바뀌고, 개수 옆의 Get more 링크가 업그레이드 창을 열어요. 그 창은 하나 더 쓸 여유가 있는 가장 작은 플랜을 알려줘요.

#웹훅 추가

목록의 각 웹훅에는 주소, 메모, 이벤트, 서명에 쓰는 시크릿(앞 몇 글자), 마지막 전송 결과가 표시돼요. 스위치로 On 또는 Off로 바꾸고, 점 세 개 메뉴에는 Send a test event(한 시간에 최대 열 번, 켜져 있을 때만), Change, New signing secret, Delete가 있어요.

#배송은 이런 모습이에요

모든 전송에는 같은 세 부분이 있어요. type(이벤트 코드), timestamp(일어난 시각, UTC), data(세부 내용)예요. 양식 제출의 예시예요.

전송마다 헤더 세 개도 함께 가요: webhook-id(메시지의 id), webhook-timestamp(보낸 시각, 초 단위), webhook-signature예요. 열린 Standard Webhooks 형식을 따르기 때문에, 이를 이해하는 도구가 전송을 대신 확인할 수 있어요.

#전달이 진짜인지 확인하기

누구나 주소로 메시지를 보낼 수 있으니, 받는 쪽에서 믿기 전에 서명을 확인해야 해요. 서명은 나와 Briks만 아는 서명 시크릿으로 만들어요. 프로젝트에 웹훅이 생기면 Webhooks 페이지의 Checking a delivery is genuine 아래에 짧은 코드 예시가 나와요. 말로 풀면 확인 과정은 이래요:

1. 본문을 JSON으로 읽기 전에, 도착한 그대로 텍스트로 가져오세요.
2. webhook-id, webhook-timestamp, 본문을 마침표로 이어 붙이세요.
3. 시크릿에서 맨 앞의 whsec_를 빼고 나머지를 base64로 디코딩하세요. 그 값이 키예요.
4. 이어 붙인 텍스트를 이 키로 HMAC SHA-256 서명하고, 결과를 base64로 적은 다음 앞에 v1,을 붙이세요.
5. 그 값이 webhook-signature에 공백으로 구분된 값 중 하나와 일치하고 타임스탬프가 현재 시각에서 5분 이내라면 진짜 전송이에요.

다시 시도되는 전송은 webhook-id를 그대로 유지하므로, 수신 측에서 처리한 id를 저장해 두고 중복을 건너뛸 수 있어요.

#전달과 재시도

Deliveries에는 최근 30일 동안의 전송 내역이 최신순으로 모두 나와요. Status로 범위를 좁히고 Show를 누르세요. 하나를 클릭하면 전체 메시지와 오류, 해당 주소가 응답한 내용을 볼 수 있어요.

각 시도는 응답을 최대 15초 기다려요. 응답이 2xx가 아니면 Briks가 다시 시도해요. 총 다섯 번이고, 첫 번째는 즉시, 그다음은 약 30초, 2분, 8분, 32분 뒤에 해요. 처음부터 마지막까지 대략 45분이에요. 410(gone) 응답을 받으면 재시도를 바로 멈춰요. 리다이렉트는 따라가지 않으니 최종 주소를 입력하세요.

전송이 Failed 또는 Delivered가 되면 Send again으로 같은 id의 같은 메시지를 새로 서명해 다시 보내요. 웹훅이 켜져 있어야 해요.

#인사이트와 설정

Insights는 지난 30일을 요약해요. Deliveries, 전달된 비율 Delivered, Failed after every try(다시 시도한 횟수 포함), 그리고 Average answer 시간이에요. 아래의 By event와 By address에서 실패가 몰리는 곳을 볼 수 있어요.

Settings의 Download the webhooks 아래에 Download JSON이 있고, 모든 웹훅의 주소, 이벤트, 메모가 담겨요. 서명 비밀 키는 포함되지 않아요. 위험 영역에는 전송 로그를 지우고 재시도를 멈추는 Clear log와, 프로젝트 이름을 입력하면 모든 웹훅을 없애는 Delete all이 있어요. 둘 다 Owner와 Admin만 쓸 수 있어요.

#활용 예시: 양식 응답을 다른 도구로 보내기

스튜디오에서는 폼 응답을 내보낼 수 없어요. 그래서 응답이 들어올 때마다 다른 도구에 보관하려면 웹훅을 쓰세요. 스튜디오에도 응답이 남아요. 최근 100건이 Settings, Forms에 표시돼요.