Webhook とイベント
アカウントの Webhook は、アカウント全体で起きたこと(新しいリード、予約されたミーティング、ステージが変わった商談など)を、指定した URL にリアルタイムで送ります。Zapier と n8n の連携も内部でこれを使っており、独自のエンドポイントに送ることもできます。Zapier だけを使う場合は、Webhook を自分で追加する必要はありません。開発者向け ページの Zapier カードからテンプレートで Zap を始めれば、Zap が自分で Webhook を設定します。
各メールの回答ページにあるプロジェクトの Webhook はこれまでどおり使えます。プロジェクトの Webhook は1通のメールのインタラクションを扱い、アカウントの Webhook はすべてのメールと下記のイベントを扱います。署名の方式は同じです。
Webhook を追加する
- ダッシュボードの 開発者向け を開き、Webhook カードを探します。
- エンドポイント URL(公開された
https://の URL)を入力し、必要な イベント にチェックを入れます。 - Webhook を追加 をクリックし、署名シークレット をコピーします。表示されるのはこの一度だけです。
各 Webhook には、作成元(ダッシュボード、API、Zapier、n8n)、状態、最終配信日時が表示されます。テストを送信 は、選んだイベントのサンプルを data に "test": true を付けて送ります。削除 で Webhook を削除します。1つのアカウントで最大50件まで作成できます。
Webhook の追加と削除はアカウントのオーナーだけが行えます。操作の前に再ログインを求められる場合があります。
イベント
| イベント | 発生するタイミング |
|---|---|
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 | 受信者が、メールの対象となるすべてのブロック(アンケートのすべての質問など)に回答したとき。受信者とメールごとに 1 回です。 |
review.submitted | 受信者が、レビュー依頼ブロックからレビューを送信したとき。レビューごとに 1 回です。 |
連絡先のイベントは、インポート、登録フォーム、API、同期、AI コネクタで発生します。1回の書き込みで500件を超える連絡先(大きな CSV インポートなど)の場合は発生しないため、インポートで数千のワークフローが動くことはありません。連絡先グリッドで追加した連絡先(手入力でも CSV からの取り込みでも)は contact.created を発生させます。グリッドでの既存の連絡先の編集、ジャーニーの フィールドを更新 ステップ、保存された回答では contact.updated は発生しません。
lead.hot と lead.new は、リードアラートのスイッチや制限とは関係なく発生します。購読すること自体が同意になります。
どちらの実験イベントにも {experiment} が含まれます。形は実験 API が返すものと同じで、バリアント、分析による最新の result、記録された decision と分析が示した evidence、そして resultsUrl が入っています。experiment.completed は実験ごとに1回だけ発生します。逐次検定で判断が早めに記録された場合も同じです。ジャーニー内の実験では、勝者は経路で示されます(decision.pathIndex)。
response.completed には、メール(projectId、projectName)、recipient キーとその contact、送信で配信された場合の sendId と variant(それ以外は null)、対象の blockIds、そして answers に各ブロックの回答(interaction.received が event.value に含めるのと同じ値)と、firstAnsweredAt、completedAt が含まれます。メールは、受信者に表示されるすべてのアンケート、評価、クイズ、RSVP、フォームを対象にします。スタジオの「回答」パネルで減らすこともでき、対象が 2 つ未満だと発生しません。後から回答を変えても再度発生せず、受信者のない表示(プレビュー、共通リンク)は完了になりません。
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 のヘッダーが付き、プロジェクトの Webhook とまったく同じ方法で計算されています。署名シークレットを使って生のボディに対して検証し、数分以上前のタイムスタンプは拒否してください。そのまま使える Node.js の関数がプロジェクトの Webhook のドキュメントにあります。
再試行
エンドポイントは5秒以内に 2xx を返す必要があります。それ以外(タイムアウト、エラーステータス、リダイレクト)は失敗として扱われ、同じボディと同じ冪等キーで、Webhook の現在の URL に向けて、間隔を広げながら数時間にわたり自動で再試行されます。すぐに応答を返し、時間のかかる処理はその後に行ってください。
- エンドポイントが
410 Goneを返すと、Webhook は無効になります。REST Hooks のクライアントはこの方法で購読を解除します。 - API キーを無効化 すると、そのキーで作成した Webhook も無効になります。
- Webhook を削除すると、保留中の再試行も止まります。
API で購読する
Zapier、n8n、独自のコードは、API キー(Authorization: Bearer mia_live_…)で Webhook を管理できます。
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 が含まれます。secret は二度と返されないので、保管してください。GET /api/v1/webhooks で購読の一覧を取得し、DELETE /api/v1/webhooks/{id} で削除します。不明なイベント名が1つでもあると、リクエスト全体が拒否されます。これらのルートは、キーごとに1分あたり30リクエストまでです。
完全な仕様は OpenAPI 仕様にあります。
実験の結果を取得する
API キーがあれば、独自のコードから実験を読み取れます。たとえば experiment.completed を受け取った時点で数値を取得できます。
GET /api/v1/experimentsは実験を新しい順に一覧します。status、kind(sendまたはjourney)、projectId、journeyIdで絞り込めます。GET /api/v1/experiments/{id}は1件の実験を返します。GET /api/v1/experiments/{id}/resultsは実験を完全なレポート付きで返します。数値は結果ページの JSON エクスポートと同じで、集計値のみです。
これらのルートは読み取り専用です。ロック、開始、判断の記録、勝者の展開はダッシュボードで行います。キーごとに1分あたり60リクエストまでです。数値の意味は実験結果の読み方で説明しています。