データベースWebhook入門：データが変わったらアクションを発火する

ほぼすべてのアプリがいつか直面する問題があります。データベースで何かが起きて、システムの他の部分がそれを知る必要がある、という問題です。

ユーザーが登録した——Stripeに通知するか、ウェルカムメールを送るべき。注文ステータスが支払い済みに変わった——フルフィルメントサービスが拾うべき。サポートチケットが解決済みになった——誰かのダッシュボードが更新されるべき。古典的な方法はアプリにコードを書くことです。行を保存したあと、メールサービスを呼び、フルフィルメントAPIを呼び、キャッシュを更新する。これは機能しますが、おそらく出会ったことのある失敗モードがあります。アプリだけがそれらの反応をトリガーできる、ということです。トリガーが増えるたびにアプリケーションコードの修正が必要になり、変更を知る必要のある各システムは同じコードパスから呼ばれなければなりません。そしてアプリの外でレコードが変更された瞬間——サポート担当が管理ツールで編集し、スクリプトがバッチインポートし、誰かがデータベースで直接データを修正する——何も発火しません。

データベースWebhookはまさにそれを解決するために存在します。アプリケーションがいつ外部に通知するかを決めるのではなく、データベースイベント自体が決めるのです。Webhookとは、行が作成・更新・削除されるたびに、あなたが管理するエンドポイントへデータベース（またはその上に載るツール）が送るHTTPリクエストです。APIはイベントを受け取り、必要なことを行います——メールを送り、サービスを呼び、キャッシュを更新——そして変更がどこから来たかにかかわらず動作します。

この記事では、データベースWebhookの仕組み、本当に得意なこと、そして配線する価値のあるパターンを実践的に解説します。

データベースWebhookとは何か

Webhookは統合における最もシンプルなアイデアです。「Xが起きたら、このURLを呼ぶ」。データベースの世界では、Xはデータの変更——行の挿入、更新、削除——であり、URLはあなた自身のサーバー上にある、あなたが書くエンドポイントです。

フローはこうなります：

データベースで行が作成/更新/削除される
        ↓
Webhook発火：POST https://api.your-app.com/webhooks/order-updated
        ↓
エンドポイントがペイロードを受け取る（どの行、何が変わったか）
        ↓
コードが後続処理をする：メール、同期、通知、キャッシュ

ペイロードが重要です。良いWebhookは「何かが変わった」と言うだけではありません。何が変わったのか——テーブル、レコードID、変わったフィールド、場合によっては行全体——を教えてくれます。それによってエンドポイントは、何が起きたかを把握するためにデータベースに戻ることなく、イベントに基づいて行動できます。

「データが変わったらURLを呼ぶ」には2つの流派があります。

• データベースレベルWebhook：データベース自体（またはその上のトリガー/サイドカー）がリクエストを送ります。Postgresはネイティブにこれをやらないため、トリガー関数、pgwebhookのようなツール、または変更を監視する管理レイヤーを使うことになります。
• 管理レイヤーWebhook（私がBasevoltで作っている種類）：データベースを操作するためのパネルやツールが、挿入・更新・削除のたびにリクエストを送ります。UIで行った変更、AIエージェントがMCP経由で行った変更、バッチインポートされた変更も含みます。「ordersの行が更新され、statusがpaidになったら、このエンドポイントにPOST」と定義します。

2つ目が実用的なことが多い理由は、データに触れるすべての経路を捉えるからです。アプリケーションコードがたまたま呼ぶものだけでなく。

Webhookとアクションボタン：一つのアイデアの二つの半分

最近データベースツールを見たなら、「Webhook」と「アクションボタン」が一緒に語られているのを見るでしょう。この違いを正確にしておく価値があります。補完的な問題を解決するからです。

Webhookは自動です。データが変わると発火し、人間は関与しません。注文ステータスがpaidになる→エンドポイント発火→確認メール送信。自動で起こるべきことに使います。

アクションボタンは手動です。行に置くボタン——「返金を承認」「発送済みにする」——で、人間がクリックするとエンドポイントへHTTPリクエストを送ります。ボタンはレコードのデータを運ぶので、エンドポイントはどの注文が承認されたかを正確に知ります。何かが起こる前に人間の判断が必要なことに使います。

この2つが組み合わさって、実際にビジネスを回すパターンになります。人間が注文で「返金を承認」をクリックし、アクションボタンが返金APIを呼び、APIが行を更新し、その更新に紐づくWebhookが発火し、システムの残り（メール、経理、在庫）が反応します。人間が判断を下し、機械がその後のすべてを行いました。

データベースWebhookが本当に得意なこと

私が見てきた有効なパターンを、配線する価値が高い順に紹介します。

1. そうでなければ送り忘れる通知

定番です。leadsに新しい行→営業チャネルに通知。ordersの行がpaidに→確認メールを送信。チケットがresolvedに→依頼者に通知。通知がアプリの保存パスではなくWebhookに載っていれば、呼び忘れたコードパスによってスキップされることはありません。しかも変更がスクリプト、管理画面での編集、直接のDB修正から来た場合でも発火します。

2. 他のシステムとの同期維持

真実のソースとなるデータベースがあり、そのコピーを必要とする別のシステムがある——検索インデックス、データウェアハウス、CRM、キャッシュ。すべての書き込みパスが両方を更新することを願う代わりに、変更をリプレイする小さな同期エンドポイントへWebhookを向けます。これは貧乏人のイベントバスであり、多くのアプリにとって必要なイベントバスのすべてです。

3. 承認と人間参加のワークフロー

これが過小評価されているものです。Webhook単体は完全自動——判断が必要なものには間違っています。有用なパターンはアクションボタン（人間が判断）+ Webhook（その後のすべて）。注文が返金をリクエストする：行にボタンが現れ、人が「承認」をクリックし、APIが返金を実行し、結果の更新に紐づくWebhookが経理と顧客に通知します。機械が作業をし、人間が判断を握ります。

4. 監査ログと変更フィード

すべての変更をchangesテーブル（または外部ログ）に記録するWebhookは、何が、いつ、どの経路で——UI、スクリプト、エージェント、直接SQL——起きたかの信頼できる記録を与えます。安価な監査ログであり、データパイプラインが消費できるフィードも兼ねます。

Webhookに使うべきでないこと

限界を知ることも同じくらい重要です。

重い処理にWebhookを使わない。 Webhookハンドラは速くあるべきです——イベントを受け取り、作業を開始し、200を返す。後続処理に数秒かかったり、バックオフ付きリトライが必要なら、インラインでやらずにキューに渡します。

重要な状態変更の唯一のコピーとしてWebhookに頼らない。 WebhookはHTTP上のベストエフォート配信です。ネットワークは落ち、エンドポイントは停止し、リクエストはタイムアウトします。良いシステムはWebhookを変更が起きたという信号として扱い、確実にしたいときは真実のソースと照合します。

ビジネスルールをWebhookに住まわせない。 Webhookは何が変わったかをシステムに伝えます。決めるのはシステムです。ルールが変わったとき——「今度は経理にもメールする」——変更するのはエンドポイントであって、Webhook設定ではありません。

機能するセットアップパターン

私がお勧めするセットアップパターンはこれで、Basevoltでの配線方法に対応しています——イベントを定義し、エンドポイントに向け、配信を検査可能に保つ。

ステップ1——トリガーを正確に選ぶ。 「ordersの更新のたび」は広すぎます。「orders.statusがpaidに変わったとき」こそ意味のあるトリガーです。ほとんどのツールは変更後の値でフィルタでき、そのフィルタこそ価値の場所です。

ステップ2——速いエンドポイントを書く。 ペイロードをパースし、小さなことを一つ行い、200を返すべきです。作業が重ければキューに入れます。エンドポイントは冪等に——同じイベントが2回届いても、2回処理しても無害であるべきです。

ステップ3——配信を可視化する。 何かが届かないとき、それを知る必要があります。配信ログ——各リクエスト、ステータスコード、所要時間——と失敗用の再試行ボタンがあれば、Webhookは「時々動くもの」から、実際に運用できるものに変わります。

AIがアプリを書く時代にこれがより重要な理由

ここがここ2年で新しい部分です。ClaudeやCursorで構築しているなら、Webhookはエージェントが書いたアプリと、その周りのビジネス運用の間の自然な橋です。エージェントは、スキーマを設定したのと同じようにMCP経由で、配線全体——行のアクションボタン、ステータス変更のWebhook、エンドポイント契約——を設定できます。統合レイヤーを手書きするのではなく、エージェントが設定したものをレビューし、パネルでリアルタイムに発火を確認するのです。

より深い点：エージェントが作ったアプリは、ロジックの多くがデータベース（スキーマ、ステータス、リレーション）にあり、手作りのグルーコードに少なくある傾向があります。そのためWebhookのようなイベント駆動パターンがより適しています——データベースが唯一の真実のソースであり、Webhookは外界がその変更を聞く方法なのです。

まとめ

データベースWebhookは小さなアイデアで、見返りは不釣り合いに大きいものです。「この変更を世界に伝える」をアプリケーションコードからデータ自体へ移します。通知、同期、承認ワークフローの自動の半分に使い、ハンドラは速く・冪等に・可視に保ち、人間の判断が先に来るべきときはアクションボタンと組み合わせます。

エンドポイントを手書きせずにこのパターンを見てみたいなら、Basevoltは全プランに配信ログと再試行付きのWebhookとアクションボタンを搭載しています。データベースを接続し、WebhookをAPIに向け、行のボタンをクリックしてリクエストが飛ぶのを見てください。「データが変わった」から「世界が反応した」まで、私が知る最短ルートです。