웹훅과 이벤트
계정 웹훅은 계정 전체에서 일어나는 일(새 리드, 예약된 미팅, 단계가 바뀐 거래 등)을 내가 정한 URL로 실시간으로 보냅니다. Zapier와 n8n 연동도 내부적으로 이것을 사용하며, 내 엔드포인트로 보낼 수도 있습니다. Zapier만 사용한다면 웹훅을 직접 추가할 필요가 없습니다. 개발자 페이지의 Zapier 카드에서 템플릿으로 Zap을 시작하면 Zap이 자체 웹훅을 설정합니다.
각 이메일의 응답 페이지에 있는 프로젝트 웹훅은 그대로 쓸 수 있습니다. 프로젝트 웹훅은 이메일 한 통의 상호작용만 다루고, 계정 웹훅은 모든 이메일과 아래 이벤트를 다룹니다. 서명 방식은 같습니다.
웹훅 추가하기
- 대시보드에서 개발자로 가서 웹훅 카드를 찾습니다.
- 엔드포인트 URL(공개된
https://URL)을 입력하고 원하는 이벤트를 선택합니다. - 웹훅 추가를 클릭하고 서명 시크릿을 복사합니다. 이번 한 번만 표시됩니다.
각 웹훅에는 만든 경로(대시보드, API, Zapier, n8n), 상태, 마지막 전달 시각이 표시됩니다. 테스트 보내기는 선택한 이벤트의 샘플을 data에 "test": true를 붙여 보냅니다. 삭제로 웹훅을 지웁니다. 계정당 최대 50개까지 만들 수 있습니다.
웹훅 추가와 삭제는 계정 소유자만 할 수 있으며, 먼저 다시 로그인하라는 요청을 받을 수 있습니다.
이벤트
| 이벤트 | 발생 시점 |
|---|---|
interaction.received | 수신자가 이메일에서 상호작용할 때(투표, 평가, 퀴즈 응답, 추적 클릭, 구매 등). 중복으로 걸러진 동작은 발생하지 않습니다. |
form.submitted | 이메일 속 양식(source: "email-form")이나 가입 양식(source: "signup-form")이 제출될 때. |
contact.created | 연락처가 목록에 추가될 때. |
contact.updated | 연락처의 필드가 바뀔 때. 같은 데이터를 다시 저장하면 발생하지 않습니다. |
lead.hot | 연락처의 참여도 점수가 핫 리드 기준값을 위로 넘을 때. |
lead.new | 가입 양식이나 이메일 속 양식으로 새 리드가 들어올 때. |
booking.created | 미팅이 예약될 때. |
booking.cancelled | 예약이 취소될 때(cancelledBy 포함). 일정 변경은 두 예약 이벤트 모두 발생시키지 않습니다. |
deal.created | 거래가 만들어질 때. 보드, 자동 규칙, 여정, 제안서, API 등 어디서든 해당됩니다. |
deal.stage_changed | 거래의 단계가 바뀔 때(성사와 실패 포함). |
purchase.completed | 수신자가 이메일 내 결제로 결제할 때. |
journey.completed | 연락처가 여정의 끝에 도달할 때. 중간에 나간 경우는 포함되지 않습니다. |
experiment.decided | 누군가 실험의 결정(승자, 차이 없음, 결론 없음)을 기록할 때. |
experiment.completed | 실험의 최종 결과가 나왔을 때. 관찰 기간 전체를 다루는 분석이 실행된 시점입니다. |
response.completed | 수신자가 이메일에 포함되는 모든 블록(예: 설문의 모든 질문)에 응답했을 때. 수신자와 이메일마다 한 번입니다. |
review.submitted | 수신자가 리뷰 요청 블록에서 리뷰를 보냈을 때. 리뷰당 한 번 발생합니다. |
연락처 이벤트는 가져오기, 가입 양식, API, 동기화, AI 커넥터에서 발생합니다. 한 번에 500명을 넘는 연락처를 쓰는 경우(큰 CSV 가져오기 등)에는 발생하지 않으므로, 가져오기 한 번으로 워크플로가 수천 개 실행되지 않습니다. 연락처 표에서 추가한 연락처는 직접 입력했든 CSV에서 병합했든 contact.created를 발생시킵니다. 표에서 기존 연락처를 편집하거나, 여정의 필드 업데이트 단계, 저장된 응답은 contact.updated를 발생시키지 않습니다.
lead.hot과 lead.new는 리드 알림의 스위치나 제한과 상관없이 발생합니다. 구독하는 것 자체가 동의입니다.
두 실험 이벤트에는 모두 {experiment}가 담깁니다. 실험 API가 응답하는 것과 같은 형태로, 변형, 분석의 최신 result, 분석이 부여한 evidence가 포함된 기록된 decision, 그리고 resultsUrl이 들어 있습니다. experiment.completed는 실험마다 한 번만 발생하며, 순차 검정에서 결정을 일찍 기록한 경우에도 마찬가지입니다. 여정 안의 실험에서는 승자가 경로를 가리킵니다(decision.pathIndex).
response.completed에는 이메일(projectId, projectName), recipient 키와 그 contact, 발송으로 보낸 경우의 sendId와 variant(아니면 null), 포함된 blockIds, 그리고 answers에 각 블록의 응답(interaction.received가 event.value에 담는 것과 같은 값)과 firstAnsweredAt, completedAt이 담깁니다. 이메일은 수신자에게 보이는 모든 투표, 평점, 퀴즈, RSVP, 양식을 포함하며, 스튜디오의 응답 패널에서 줄일 수 있습니다. 포함되는 블록이 두 개 미만이면 발생하지 않습니다. 나중에 응답을 바꿔도 다시 발생하지 않으며, 수신자가 없는 보기(미리보기, 공용 링크)는 완료되지 않습니다.
review.submitted에는 이메일(projectId, projectName), blockId, subject(kind, id, title)에 리뷰 대상, rating, title과 body, 고른 displayName, verifiedPurchase, contact와 recipient, submittedAt이 담깁니다.
페이로드
모든 전달은 같은 형식의 JSON POST입니다.
{
"id": "evt_8c1f…",
"type": "deal.stage_changed",
"createdAt": 1790000000000,
"data": {
"deal": {
"id": "deal_abc123",
"title": "Annual plan",
"value": 1200,
"currency": "USD",
"pipelineId": "owner_default",
"stageId": "proposal-sent",
"stage": "Proposal sent",
"status": "open",
"source": "manual",
"listId": "list_abc123",
"rowId": "3f6c1b0e2d…",
"email": "[email protected]"
},
"fromStageId": "meeting-booked"
}
}
id는 같은 이벤트의 모든 전달에서 같으며 X-MailInApp-Idempotency-Key 헤더로도 전달됩니다. 이미 처리한 재전달은 안전하게 버릴 수 있습니다. createdAt은 에포크 밀리초입니다.
이벤트 유형별 data 내용은 GET /api/v1/events/sample을 호출하거나 테스트 보내기로 확인하세요.
서명 검증하기
전달에는 X-MailInApp-Timestamp와 X-MailInApp-Signature 헤더가 붙으며, 프로젝트 웹훅과 똑같은 방식으로 계산됩니다. 서명 시크릿으로 원본 본문에 대해 검증하고, 몇 분 이상 지난 타임스탬프는 거부하세요. 바로 쓸 수 있는 Node.js 함수가 프로젝트 웹훅 문서에 있습니다.
재시도
엔드포인트는 5초 안에 2xx로 응답해야 합니다. 그 밖의 경우(시간 초과, 오류 상태, 리디렉션)는 실패로 처리되며, 같은 본문과 같은 멱등 키로 웹훅의 현재 URL에 간격을 늘려 가며 몇 시간 동안 자동으로 재시도합니다. 빠르게 응답하고, 오래 걸리는 작업은 그 뒤에 처리하세요.
- 엔드포인트가
410 Gone으로 응답하면 웹훅이 비활성화됩니다. REST Hooks 클라이언트는 이 방법으로 구독을 해지합니다. - API 키를 폐기하면 그 키로 만든 웹훅도 비활성화됩니다.
- 웹훅을 삭제하면 대기 중인 재시도도 멈춥니다.
API로 구독하기
Zapier, n8n, 내 코드는 API 키(Authorization: Bearer mia_live_…)로 웹훅을 관리할 수 있습니다.
curl https://mailinapp.com/api/v1/webhooks \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'
201 응답에는 구독의 id와 모든 전달에 서명하는 secret이 들어 있습니다. 다시 반환되지 않으니 보관하세요. GET /api/v1/webhooks로 구독 목록을 보고, DELETE /api/v1/webhooks/{id}로 하나를 삭제합니다. 알 수 없는 이벤트 이름이 하나라도 있으면 요청 전체가 거부됩니다. 이 경로들은 키당 분당 30개 요청까지 허용합니다.
전체 규격은 OpenAPI 명세에 있습니다.
실험 결과 조회하기
API 키가 있으면 내 코드에서 실험을 읽을 수 있습니다. 예를 들어 experiment.completed가 도착했을 때 수치를 가져올 수 있습니다.
GET /api/v1/experiments는 실험을 최신순으로 나열합니다.status,kind(send또는journey),projectId,journeyId로 필터링할 수 있습니다.GET /api/v1/experiments/{id}는 실험 하나를 반환합니다.GET /api/v1/experiments/{id}/results는 실험을 전체 보고서와 함께 반환합니다. 결과 페이지의 JSON 내보내기와 같은 수치이며, 집계값만 담깁니다.
이 경로들은 읽기만 합니다. 잠그기, 시작, 결정, 우승안 배포는 대시보드에서만 할 수 있습니다. 키당 분당 60개 요청까지 허용합니다. 수치의 의미는 실험 결과 읽기에서 설명합니다.