Notion Webhook連携の考え方｜DB更新を外部処理につなぐ設計

Notion Webhookは、Notion内の操作やデータベース更新を外部処理につなぐための仕組みです。

たとえば、次のような使い方があります。

• 問い合わせDBの新規行を自社APIへ送る
• ステータスが「外部処理待ち」になったらMakeやZapierへ渡す
• Notionページの変更イベントを受け、最新データをAPIで取得する
• 外部処理の結果をログDBや確認ビューに戻す
• AI分類、チケット作成、通知、集計などの後続処理を動かす

ただし、NotionのWebhookは1種類ではありません。

実務では、次の2つを分ける必要があります。

種類	何をするか	主な利用者
Webhookアクション	ボタンやDBオートメーションから外部URLへHTTP POSTを送る	業務担当、管理者、ノーコード運用
開発者Webhook	Notion内のページやDB変更イベントを外部エンドポイントで受ける	開発者、連携基盤の管理者

Notion公式ヘルプでは、Webhookアクションはボタン、データベースボタン、データベースオートメーションの Send webhook アクションから、特定URLへHTTP POSTリクエストを送れると説明されています。

Notion公式ヘルプ：Webhook actions

一方、開発者向けWebhookは、ページやデータベースの変更をリアルタイムに監視するための仕組みです。公式開発者ドキュメントでは、イベント自体は変更後の完全な内容を含まず、何かが変わった合図として受け取り、必要に応じてNotion APIで最新データを取得すると説明されています。

Notion公式開発者ドキュメント：Webhooks

Notion Webhook連携は、URLに送れば終わりではありません。Webhookを合図として扱い、受信API、認証、ログ、再実行、人の確認点まで設計する必要があります。

この記事では、Notion Webhook連携の考え方を、2種類のWebhook、Webhookアクション、開発者Webhook、送れるデータと制約、受信API、エラー監視、使わない方がよいケースまで整理します。

Notionオートメーションの使い方はこちら
Notionインテグレーションの基本はこちら
NotionとChatGPT連携の考え方はこちら
Notion AI APIの現実的な設計はこちら
MakeとNotion連携の作り方はこちら

先に結論：Webhookは処理本体ではなく合図として扱う

Webhookを設計するときは、Webhookそのものに業務処理を背負わせない方が安全です。

Webhookは、次の流れの入口です。

段階	役割
Notion側	条件に合う更新や操作を検知する
Webhook	外部URLへイベントやプロパティを送る
受信API	認証、重複確認、入力検証を行う
処理基盤	外部API、AI処理、チケット作成、通知を実行する
ログ	成功、失敗、再実行待ちを残す
Notion側の確認	処理結果、人の承認、例外対応をDBで見る

この流れを分けないと、次の問題が起きます。

• Notionから送ったが、外部側で失敗している
• 同じイベントが複数回処理される
• 誰が再実行すべきか分からない
• Webhookで個人情報を外部に送りすぎる
• ページ本文まで送れる前提で設計してしまう
• Notionと外部システムのどちらが正か分からない

Webhookは、受信API、ログ、再実行、人の確認とセットで設計します。

2種類のWebhookを分ける

NotionのWebhookで混乱しやすいのは、Webhookアクションと開発者Webhookを同じものとして扱うことです。

この2つは目的が違います。

比較	Webhookアクション	開発者Webhook
起点	ボタン、DBボタン、DBオートメーション	Notion connectionのWebhook購読
方向	Notionから外部URLへ送る	Notionの変更イベントを外部が受ける
使い方	ステータス変更時に外部処理を開始する	ページやDB変更を監視して後続処理する
主な制約	POSTのみ、DBページプロパティ中心、最大数あり	イベントは合図であり、最新データ取得はAPI側で行う
管理者	DB管理者、業務担当、管理者	開発者、連携基盤管理者

Webhookアクションは、Notion内の業務ルールから外部へ処理を投げる用途です。

開発者Webhookは、Notion側の変更を外部アプリや連携基盤が継続的に監視する用途です。

小さな業務自動化では、まずWebhookアクションで足りることが多いです。

一方で、複数DBを監視したい、ページ更新を継続的に受けたい、外部アプリとしてワークスペース全体に近い監視をしたい場合は、開発者Webhookを検討します。

Webhookアクションでできること

Webhookアクションは、Notionのボタン、データベースボタン、データベースオートメーションから使います。

公式ヘルプでは、Send webhook アクションで任意のURLへHTTP POSTを送り、必要に応じてカスタムヘッダーを追加できると説明されています。

実務で使いやすいのは、次のような処理です。

使い方	例
受付を外部処理へ渡す	問い合わせDBの新規行を自社APIへ送る
ステータス変更で処理開始	「外部処理待ち」になったらWebhookを送る
ノーコード基盤へ渡す	Make、Zapierでチケット作成や通知を行う
AI処理を起動する	問い合わせ分類や要約の下書きを作る
ログを外部に残す	送信履歴、失敗、再実行待ちを記録する

ただし、Webhookアクションには制約があります。

公式ヘルプでは、主に次の制約が説明されています。

制約	実務での意味
POSTのみ	GET、PUT、DELETEを直接使い分ける設計ではない
最大5つまで	1つの自動化に外部送信を詰め込まない
ワークスペースレベルではない	DBやボタン単位で考える
DBページプロパティを送る	ページ本文をそのまま送る前提にしない
ペイロードの事前プレビューがない	検証用エンドポイントやログで確認する
失敗時に一時停止する	監視と復旧手順が必要

Webhookアクションを使うなら、送るプロパティを絞ります。

送ってよい項目	送る前に確認する項目
ページID、外部連携ID、ステータス、種別、期限	氏名、メール、契約情報、金額、添付、本文
担当チーム、処理種別、再実行フラグ	個人情報、社外秘、顧客別メモ

Notionにある情報をすべて外部へ送るのではなく、受信側に必要な項目だけを送ります。

開発者Webhookでできること

開発者Webhookは、Notion connection側でWebhookを設定し、ページやデータベースの変更イベントを外部エンドポイントで受ける仕組みです。

公式ドキュメントでは、ページ作成、ページプロパティ更新、ページ内容更新、ページ移動、削除、復元、データベースやデータソースの変更、コメントの作成・更新・削除などのイベントが整理されています。

ただし、イベントは完全なデータではありません。

公式ドキュメントでは、Webhookイベントは変更が起きた合図であり、最新状態が必要な場合はNotion APIで取得することが推奨されています。また、高頻度イベントは集約されることがあり、イベントの順序が発生順と異なる場合があるため、timestampを使った並べ替えが必要になることも説明されています。

実務では、次のように設計します。

処理	設計
イベント受信	WebhookエンドポイントでイベントID、種類、対象IDを受ける
署名検証	Notionからのリクエストか確認する
重複確認	イベントIDや対象IDで二重処理を避ける
最新取得	必要に応じてNotion APIでページやDBを取得する
処理実行	外部DB更新、チケット作成、AI分類、通知など
ログ	成功、失敗、再試行回数、処理対象を残す
Notion反映	必要な場合だけステータスや処理結果をNotionに戻す

開発者Webhookは、Webhookアクションより柔軟です。

その代わり、実装責任も増えます。

受信サーバー、認証、署名検証、API取得、キュー、ログ、再試行、権限、障害対応まで必要になります。

送れるデータと制約

Webhook設計で最初に確認すべきなのは、何を送れるかです。

Webhookアクションでは、DBページのプロパティを中心に送ります。ページ本文を丸ごと送る前提にはしません。

開発者Webhookでは、イベントに対象IDやイベント種別などが含まれますが、変更後の完全な内容はイベントだけでは足りない場合があります。最新のページやデータベース内容が必要なら、Notion APIで取得します。

実務では、送信項目を次のように分けます。

項目	扱い
ページID	外部処理のキーに使う
外部連携ID	再実行や重複防止に使う
ステータス	処理条件や確認状態に使う
種別	処理ルートを分ける
担当者	通知や確認者の判断に使う
本文	送れる前提にせず、必要ならAPI取得する
添付	Webhookで直接扱わず、原本の保管先を確認する
個人情報	最小限にし、外部側の保管と削除手順を確認する

送信項目を増やすほど、外部側の管理責任が増えます。

Webhookは、Notion内で見えている情報を外へ出す境界です。

Notionセキュリティの基本はこちら

受信APIの設計

NotionからWebhookを送るなら、受信APIを先に設計します。

最低限、次の項目を決めます。

項目	決めること
URL	本番用、検証用、停止用を分ける
認証	カスタムヘッダー、署名検証、受信側の秘密値
入力検証	必須項目、ステータス、対象DBを確認する
重複防止	イベントID、ページID、外部連携IDを使う
非同期処理	重い処理はキューやジョブへ逃がす
ログ	受信、成功、失敗、再実行待ちを記録する
応答	Notionへすばやく成功応答を返す
通知	失敗時に管理者へ通知する

Webhook受信でやってはいけないのは、受け取った瞬間に重い外部処理をすべて同期実行することです。

外部APIが遅い、AI処理に時間がかかる、相手サービスが落ちている。このような場合に、Webhook受信自体が不安定になります。

実務では、受信APIでは検証とログ登録までを素早く行い、重い処理はジョブとして後続へ回します。

受信時に行う	後続処理に回す
認証、署名、ヘッダー確認	外部API呼び出し
必須項目の検証	AI分類、要約
重複チェック	チケット作成
ログ登録	Notionへの結果反映
成功応答	再実行、例外対応

この分け方にすると、Webhookが止まりにくくなります。

エラー監視

Webhook連携で一番危ないのは、静かに失敗することです。

Notion側では送ったつもりでも、外部側で失敗している。外部側では処理したが、Notionへ戻せていない。こうした状態は、画面を見ただけでは分かりません。

ログDBまたは外部ログには、次の項目を残します。

項目	目的
受信日時	いつ受けたか
イベントID	重複処理を防ぐ
ページID	Notion側の対象を追えるようにする
Webhook種別	アクションか開発者Webhookか
処理ステータス	未処理、処理中、成功、失敗、再実行待ち
エラー内容	何で失敗したか
再実行回数	無限再実行を防ぐ
担当者	誰が復旧するか
最終確認日	放置を防ぐ

開発者Webhookでは、公式ドキュメント上、イベント配信は通常短時間で届くこと、順序が発生順と異なる場合があること、失敗時には最大8回まで再試行されることが説明されています。

そのため、受信側では次の設計が必要です。

リスク	対策
順序が前後する	timestampで並べ替える
同じ対象が何度も来る	イベントID、ページID、外部IDで重複確認する
最新状態ではない	必要に応じてNotion APIで再取得する
外部APIが失敗する	再実行キューと失敗通知を持つ
受信先が落ちる	監視、アラート、復旧手順を持つ

Webhookは送信設定より、監視設計の方が重要です。

Notionに戻すか、外部で完結させるか

Webhook処理の結果を、必ずNotionに戻す必要はありません。

ただし、業務担当者がNotionで状況を見るなら、最低限の結果は戻した方がよいです。

戻す情報	目的
外部処理ステータス	未処理、処理中、成功、失敗を見えるようにする
最終送信日時	いつ外部へ渡したか確認する
外部連携ID	外部システムと照合する
エラー概要	担当者が原因を把握する
再実行フラグ	人が再実行を判断する
確認者	成功後に誰が内容を見るか

Notionに戻すべきでない情報もあります。

外部サービス側の詳細ログ、秘密値、アクセストークン、長いスタックトレース、個人情報を含む生データは、Notionではなくログ基盤や管理画面に置く方が安全です。

Notionには、業務担当者が判断するための状態だけを戻します。

使わない方がよいケース

Webhookは便利ですが、使わない方がよいケースもあります。

使わない方がよいケース	理由
Notion内通知で足りる	外部APIを作るほどではない
手動確認で十分	自動化すると例外対応が増える
高い監査性が必要	NotionとWebhookだけでは証跡設計が足りない
双方向同期が複雑	競合、削除、上書きの設計が難しい
個人情報を外部に大量送信する	保管、削除、権限、契約確認が必要
受信APIを保守できない	障害時に誰も直せない

問い合わせ通知、軽いタスク起票、FAQ候補作成、AI要約の下書き程度ならWebhookは使いやすいです。

一方で、会計、契約、労務、正式な顧客マスタ、監査ログが必要な処理は、専用システム側のAPIや業務基盤で設計した方がよい場合があります。

Notion Webhookは、業務の入口や合図として使う。

正式な原本、証跡、承認、例外処理は、Notion外の仕組みと人の確認を含めて設計する。

この分け方をすると、Notionと外部処理を無理なくつなげます。