ウェブフック:起きたことを他のツールに知らせる

#Webhookとは

プロジェクトが別のサービスに電話をかけて、起きたことを知らせるようなものだとお考えください。相手のツールから渡されたアドレス(URL)をBriksに登録し、通知したいイベントを選ぶと、そのイベントが起きるたびにBriksがそこへメッセージを送ります。多くの自動化ツール、顧客リストのツール、スプレッドシートのアドオンで、このようなアドレスを発行できます。

技術的には、各メッセージは POST リクエストです。これは本文を伴う呼び出しで、ここではプログラムが読み取れるテキスト形式の JSON で書かれます。受け取ったツールが本文を読み、設定した内容を実行します。

record.changed は、スタジオで行った変更に反応します。Databaseタブでレコードを追加、編集、削除したとき、コレクションを空にしたとき、データベースを復元したときです。訪問者が送る予約リクエストのように、公開サイトが自動で保存するレコードでは作動しません。

form.receivedは、本番環境からの送信だけでなく、プレビューからの送信でも送られます。どちらからかは各メッセージに記されているので、連携先のツールでプレビューの送信を除外できます。

#各プランの上限

その日の呼び出し回数を使い切ると、配信は送信されず Failed と表示されます。表示文言は「Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.」です。

プロジェクトにプランが許す数のwebhookがあると、Add webhook はグレーになり、数の横の Get more リンクからアップグレードのウィンドウが開きます。そこには、もう一つ追加できる最小のプランが示されます。

#Webhookを追加する

リストの各ウェブフックには、アドレス、メモ、イベント、署名に使うシークレット(最初の数文字)、直近の配信の結果が表示されます。スイッチで On と Off を切り替えられ、三点メニューには Send a test event(1時間に最大10回まで、オンのときのみ)、Change、New signing secret、Delete があります。

#納品のイメージ

どの配信も同じ3つの部分でできています。type(イベントのコード)、timestamp(起きた時刻、UTC)、data(詳細)です。フォーム送信の例を示します。

各配信には、webhook-id(メッセージのID)、webhook-timestamp(送信された時刻、秒単位)、webhook-signatureの3つのヘッダーも付きます。これらはオープンなStandard Webhooks形式に従っているため、対応するツールで配信を検証できます。

#配信が本物であることを確認する

アドレスには誰でもメッセージを送れるため、受け取る側は信用する前に署名を確認する必要があります。署名は、あなたとBriksだけが持つ署名用シークレットで作られます。プロジェクトにWebhookがあると、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を保存しておけば、重複をスキップできます。

#配信と再試行

Deliveries には、過去30日間の配信がすべて新しい順に並びます。Status で絞り込み、Show を押してください。1件をクリックすると、メッセージ全文、エラー、送信先アドレスからの応答を確認できます。

各試行は、応答を最大15秒待ちます。応答が2xxでなければ、Briksは再試行します。試行は全部で5回で、1回目はすぐに、その後は約30秒後、2分後、8分後、32分後に行い、最初から最後までで約45分です。410(gone)の応答が返ると、再試行はすぐに止まります。リダイレクトには従わないため、最終的なアドレスを指定してください。

配信が Failed または Delivered になったら、Send again で同じIDの同じメッセージを、署名し直して再送します。Webhookはオンになっている必要があります。

#インサイトと設定

Insights は過去30日間をまとめています。Deliveries(配信数)、Delivered(配信成功の割合)、Failed after every try(再試行の回数つき)、Average answer(平均応答時間)です。その下の By event と By address で、失敗が集中している箇所がわかります。

SettingsのDownload the webhooksの下にDownload JSONがあり、各webhookのアドレス、イベント、メモが含まれます。署名シークレットは含まれません。危険ゾーンには、配信ログを削除して再試行をすべて止めるClear logと、プロジェクト名を入力するとすべてのwebhookを削除するDelete allがあります。どちらもOwnerとAdminが使えます。

#実例:フォームの入力内容を別のツールへ送る

フォームの送信内容はスタジオからエクスポートできないため、届いた内容を別のツールに残すにはウェブフックを使います。スタジオにも保存され、最新の100件が Settings, Forms に表示されます。