---
title: "웹훅: 일어난 일을 다른 도구에 알리기 | Briks"
url: https://briks.dev/ko/docs/webhooks
description: "사이트 게시, 양식 전송, 레코드 변경 때 다른 도구로 서명된 메시지를 보내요. 페이로드, 서명, 재시도, 전송 내역을 설명해요."
last_updated: 2026-10-08
---

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

웹훅은 프로젝트에서 게시, 폼 제출, 레코드 변경 같은 일이 일어나는 순간 다른 도구로 짧은 메시지를 보내요. 이 페이지에서는 웹훅을 추가하는 방법, 메시지의 모양, 상대편이 진짜 메시지인지 확인하는 방법, 상대편이 멈췄을 때 어떻게 되는지를 설명해요.

읽는 데 7분 2026년 10월 8일 스튜디오 기준으로 확인함

## 웹훅이란

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

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

| 스튜디오에 표시되는 이벤트 | 코드 | 보내는 시점 |
| --- | --- | --- |
| **Published** | `site.published` | 사이트의 새 버전이 게시되었어요. |
| **Form received** | `form.received` | 방문자가 사이트의 폼으로 메시지를 보냈어요. |
| **Record changed** | `record.changed` | 프로젝트 데이터베이스의 레코드가 추가, 변경 또는 삭제되었어요. |

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

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

어디에

1. Projects
2. Your project
3. Settings
4. Webhooks

## 요금제별 한도

| 요금제 | 프로젝트당 웹훅 수 | 모든 대시보드 플랜이 정하는 세 가지 |
| --- | --- | --- |
| Free | 1 | 2,000 |
| Starter | 5 | 5,000 |
| Pro | 10 | 10,000 |
| Studio | 25 | 50,000 |
| Agency | 50 | 100,000 |

하루 호출 횟수는 예약 작업과 함께 나눠 써요. 재시도를 포함해 전송을 시도할 때마다 1번으로 세고, 하루는 UTC 자정에 시작해요.

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

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

## 웹훅 추가

1. Add webhook 누르기

   위치: Settings, Webhooks

   페이지에는 요금제 한도 대비 몇 개를 쓰고 있는지 보여 줘요. 예를 들면 요금제 한도 5개 중 1개처럼요. Editor, Admin, Owner가 웹훅을 추가할 수 있어요.

2. 주소 입력

   위치: Add a webhook

   다른 도구가 알려 준 주소를 **Address** 에 붙여넣으세요. 숫자가 아닌 이름으로 쓴 공개 https 주소여야 해요.

3. 메모 추가

   위치: Add a webhook

   **Note** 는 선택 사항이며 최대 120자까지 쓸 수 있어요. 나중에 웹훅을 구분하는 데 도움이 돼요. 예를 들면 `Enquiries sheet`처럼요.

4. 이벤트 선택하기

   위치: Add a webhook

   알림을 받을 이벤트를 체크하세요. **Published** 와 **Form received** 는 기본으로 체크되어 있고, 필요에 맞게 바꿀 수 있어요.

5. 시크릿 저장하고 복사하기

   위치: Your signing secret

   **Add webhook** 을 누르세요. 대화상자에 `whsec_`로 시작하는 서명 시크릿이 표시돼요. **Copy** 를 눌러 보관하세요. 한 번만 표시돼요. 그런 다음 **Done** 을 누르세요.

6. 테스트 보내기

   위치: Settings, Webhooks

   웹훅의 점 세 개를 열고 **Send a test event** 를 선택하세요. 이렇게 표시돼요: A test event is on its way. See how it went under Deliveries.

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

## 배송은 이런 모습이에요

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

form.received 전송

> `{"type":"form.received","timestamp":"2026-10-08T09:41:07.000Z","data":{"form":{"id":"…","subject":"결혼식 문의","page":"/contact","fields":[{"label":"이름","value":"Ellie Marsh"},{"label":"결혼식 날짜","value":"2027년 6월 14일"}],"replyTo":"ellie@example.com"},"production":true}}`

| 이벤트 | `data`에 담기는 내용 |
| --- | --- |
| `form.received` | `form`: `id`, `subject`, 보낸 `page`, `fields`(각각 `label`과 `value`, 폼의 순서대로), 그리고 `replyTo`(폼에서 이메일을 받는 경우 방문자의 이메일)가 들어 있어요. 그다음 `production`은 라이브 사이트면 `true`, 미리보기면 `false`예요. |
| `site.published` | `url`: 사이트가 공개된 주소예요. `production`: 사이트가 프로덕션에 있는지 여부예요. `abTest`: A/B 테스트가 진행 중인지 여부예요. `served`: Briks가 메시지를 보낼 때 그 주소에서 새 버전이 응답하는 것을 확인했는지 여부예요. |
| `record.changed` | `action`: `created`, `updated`, `deleted`, `cleared`, `restored` 중 하나예요. `collection`: 어떤 컬렉션인지 나타내요. `record`: 레코드의 id예요. 레코드의 값은 포함되지 않아요. |
| `test` | `message`와 `project`가 전달되고, `project`에는 `id`와 `name`이 있어요. **Send a test event** 를 누를 때만 보내요. |

전송마다 헤더 세 개도 함께 가요: `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를 저장해 두고 중복을 건너뛸 수 있어요.

비밀 키를 안전하게 보관하세요

서명 시크릿은 한 번만 표시되고 다시 볼 수 없어요. 잃어버리거나 유출되면 웹훅의 점 세 개 메뉴에서 **New signing secret** 을 고르세요. 이전 시크릿은 즉시 새 전송에 서명하지 않으니, 새 시크릿을 받는 도구에 바로 넣어 주세요.

## 전달과 재시도

어디에

1. Projects
2. Your project
3. Settings
4. Webhooks
5. Deliveries

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

| 상태 | 의미 |
| --- | --- |
| **Sending** | 첫 시도를 기다리고 있어요. |
| **Retrying** | 시도가 실패했고 다음 시도가 예정돼 있어요. 해당 줄에는 다음 시도가 언제인지 표시돼요. |
| **Delivered** | 주소가 웹에서 성공을 뜻하는 코드인 2xx 상태로 응답했어요. |
| **Failed** | 모든 시도가 실패했거나, 전송 자체를 보낼 수 없었어요. |

각 시도는 응답을 최대 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** 에 표시돼요.

요크의 웨딩 포토그래퍼가 고객 목록에 문의 메일을 보내요

1. 다른 도구에서 주소 받기

   위치: Her client list tool

   그곳에서 수신 웹훅을 만들고, 받은 주소를 복사해요.

2. 웹훅 추가하기

   위치: Settings, Webhooks

   그녀는 주소를 붙여 넣고, 메모에 `Client list`를 적고, **Published** 체크를 해제한 뒤 **Form received** 만 체크된 채로 둬요.

3. 도구에 비밀 값 알려 주기

   위치: Her client list tool

   그녀가 쓰는 도구는 서명을 확인하기 때문에, 대화상자를 닫기 전에 서명 시크릿을 도구의 설정에 붙여 넣어요.

4. 테스트해 보기

   위치: Settings, Webhooks, Deliveries

   그녀가 테스트 이벤트를 보내고, **Deliveries** 아래에 **Delivered** 로 표시되는 것을 확인해요.

5. 필드 맞추기

   위치: Her client list tool

   그녀는 `fields`의 이름, 예식 날짜, 장소 라벨을 도구의 열에 연결하고, `production`이 `false`인 메시지는 무시하라고 설정해요.

다음 문의

> 한 커플이 자신의 라이브 사이트에서 문의 양식을 작성해요.

사이트가 프로덕션에 있으므로 문의가 그녀의 받은편지함에 도착하고, 잠시 뒤 고객 목록에도 나타나요.

## 다음 글 읽기

- [사이트 기능 **폼** Briks 사이트에 양식을 추가하고, 미리보기에서 테스트하고, 스튜디오에서 문의를 확인하고, 웹훅으로 전달해요.](https://briks.dev/ko/docs/forms)
- [데이터와 자동화 **예약 작업** 예약 작업으로 정해진 시간에 사이트 작업을 실행해요. 일정 작성, 실행 결과 확인, 실패 해결, 플랜 한도까지 안내해요.](https://briks.dev/ko/docs/crons)
- [데이터와 자동화 **데이터베이스** 사이트에 저장된 데이터를 찾고, 레코드를 직접 수정·추가하고, JSON이나 CSV로 내려받아요. 권한과 한도도 안내해요.](https://briks.dev/ko/docs/database)
- [데이터와 자동화 **로그** 빌드 로그와 최근 하루의 사이트 요청을 읽고, 수준이나 상태로 걸러 실패하는 폼과 작업, 느린 페이지를 찾아요.](https://briks.dev/ko/docs/logs)

아직 해결되지 않았나요?

프로젝트 이름과 기대했던 내용을 적어 [hello@briks.dev](mailto:hello@briks.dev) 로 보내 주세요. 스크린샷이 있으면 도움이 돼요.