Webhookを使ったシステム開発の注意点

Customers Mail Cloudではメールを受信した際のWebhookを提供しています。メールを受信したタイミングで指定したURLをコールするので、メール連携型のシステムを容易に開発できます。

そうしたWebhookを使ったシステム開発時の注意点を数点、解説します。皆さんのシステム開発時に活かしてください。

WebhookはPOSTメソッド

Webhookで指定したURLに対しては、POSTメソッドで送信されるものが殆どです(GETが送られてくるものは見たことがありません)。そして、リクエストボディの中に何らかのメッセージ(Customers Mail Cloudの場合はメールに関する情報)が入ってきます。

そのため、例えばPHPであれば $_POST などを使ってリクエスト内容を取得します。Content-Typeは送信元のサービスによって異なりますが、最近ではapplication/jsonを送ってくることが多いようです。

セキュリティ対策について

WebhookのURLに対して悪意を持った人がメッセージを送ってくる可能性があります。そうした場合に備えて、Authenticationヘッダーに特定の文字列を指定できたり、Basic認証を指定できるものがあります。APIトークンではありませんが、Authenticationヘッダーを使って不正なアクセスは弾くようにしましょう。多くの場合、この時に指定できる文字列は固定であり、動的に変更することはできないようです。

開発時について

開発時はローカルでサーバーを立てて行うでしょう。もちろんWebhookでlocalhostを呼ぶのは不可能なので、外部に開発用プロキシサーバーを立てます。自分で立てることもできますが、以下のようなサービスを使うこともできます。

これらのサービスは、特定のURL(固定または動的)に対するリクエストを、ローカルホストの特定ポートへのリクエストに変換してくれます。そうやって受け取ったリクエストをパースして、システム連携に利用します。

デバッグしづらい

一度デプロイしたWebhookのURLは、後でデバッグするのがとても面倒です。実際に稼働しているサーバーに対してログインしてログをモニタリングしても、他のリクエスト情報が混ざり込んでしまうでしょう。

また、例えばGoogle Apps Scriptでは、Webhookへのリクエストログをそのままでは残せません。Google Cloudプロジェクトに変換が必要です。自社サーバーであってもログを分かるようにフィルタリングするタグを付けておく、Google Cloudプロジェクトに変換しておくと言った工夫をあらかじめ行っておきましょう。

200を確実に返す

Webhookのスクリプト内で多くの処理を行うのはお勧めしません。まず内容をファイルやデータベースに保存してしまい、そこから別スレッドで処理する方が良いでしょう。Webhookはレスポンスが返ってこないと繰り返し送られてきます(Customers Mail Cloudの場合、細かく設定できます)。そのため、冪等性の保証が必要になります。

Webhookを繰り返し呼ばれないためには、まず早めに200をレスポンスとして返すことです。その上で別スレッドにて実際の処理を行えば、安定したWebhookによる運用が実現できるでしょう。

Webhookが100%確実に呼ばれる保証はない

なお、Webhookは自分からサーバーを呼ぶ仕組みではないので、100%完璧に呼び出される保証はありません。また、ファイルやデータベースに原本を保存する前にシステムエラーが起きる可能性もあります。何らかのエラーが起きるケースも想定して開発を行うべきでしょう。

まとめ

メールの内容は様々なので、一度うまくいった方法でも運用時には失敗するということが良くあります。そのため、ログは徹底的に残しておくことをお勧めします。また、POSTされたデータをそのまま保存しておき、何かあった際にはcurlコマンドなりでリクエストを再現できるように準備しておくとデバッグしやすくなります。

Webhookは一般的なシステム開発におけるAPIリクエストとは逆の開発になりますので、ぜひ工夫しながら取り組んでください。

Webhook | Customers Mail Cloud