Webhook

Webhookはメールの送信または受信で発生するイベントを、指定されたエンドポイントに HTTPでポストするインターフェイスを提供します。


API仕様

POSTパラメータや応答メッセージのフォーマットはAPIのバージョンによって異なります。 利用するバージョンのAPI仕様を参照ください。

バージョン1

後方互換のためのバージョンです。

バージョン2

最新の機能を提供するバージョンです。 バージョン1に対してHTTPリクエストでポストするJSONへプロパティの追加などを行っています。


共通仕様

このセクションでは、Webhookの共通仕様について説明します。

項目
プロトコル HTTPS
文字コード UTF-8
改行コード LF

エンドポイント

エンドポイントとは、HTTPリクエストを受信するURLを指します。 Webhookは、メール配信状況の状態変化や、メール受信などのイベントをトリガとして、 管理GUIから設定したエンドポイントに対してイベントデータをポストします。

認証

Webhook が送信するHTTPリクエストに対して、BASIC認証またはAPIキーを使用した認証機能を エンドポイント側で実装することができます。


HTTPリクエスト

このセクションでは、Webhook が送信するHTTPリクエストの仕様について説明します。

メソッド

Webhook は、POSTメソッドのみを送信します。

ヘッダ

Webhook は、以下のヘッダフィールドを送信します。

ヘッダフィールド 説明
content-length POSTデータのサイズ
content-type POSTデータのコンテンツタイプ。下記MIMEタイプを参照。
host POST先サーバのホスト名とポート番号(例:endpoint.example.com:443)
connection Keep-Alive
user-agent Apache-HttpClient/4.4.x (Java/1.7.x_xx) xはバージョン番号
accept-encoding gzip,deflate
authorization BASIC認証を行う場合、ユーザ認証用データを送信します。

MIMEタイプ

メール配信状況を通知するEvent Webhookのエンコードタイプは、application/x-www-form-urlencoded です。 メール受信を通知する Inbound Webhook のエンコードタイプは、multipart/form-data です(添付ファイルを取り扱うため)。 エンドポイントはエンコードタイプに応じて適切にHTTPリクエストを取り扱う必要があります。

パラメータ

Webhook は全てのHTTPリクエストに、認証を行うための api_key を含め、 イベントごとに定義されたパラメータを送信します。

このドキュメントは以下フォーマットに従い、パラメータの説明を記述します。

パラメータ 必須 データ型 説明
api_key Yes ASCII 認証に使用するシークレットキー

デフォルト値、値の範囲などの制限があるパラメータについては、説明欄に以下の書式で記載します。

POSTするデータのサイズは、2MByteまでとします。


データ型

Webhook は以下の仕様に従い、データ型を取扱います。

データ型 説明
UTF-8 ASCIIを含むマルチバイト文字を表します。
ASCII 印刷可能なASCII文字を表します。
INTEGER -2147483648 から 2147483647の範囲の数値を表します。
DATE YYYY-MM-DD 形式で日付を表します。
TIME HH:mm:ss 形式で、時分秒を24時間表記で表します。
DATETIME YYYY-MM-DD HH:mm:ss 形式で年月日および時分秒を表します。
BOOLEAN true または false のいずれかを表します。

HTTPレスポンス

このセクションでは、エンドポイントから受信するHTTPレスポンスの仕様について説明します。

ステータスコード

Webhookは、エンドポイントが応答したHTTPステータスコードによって、以下の通り動作します。

コード 動作
200 リクエストは正常に処理されたとし正常終了します。
4xx 401,407,408が応答された場合、認証エラーまたは一時的なエラーと判断し、イベントの再送を試みます。それ以外の400番台のステータスコードが応答された場合、エラー終了します。
5xx 502,504が応答された場合、リバースプロキシの一時的なエラーと判断し、イベントの再送を試みます。それ以外の500番台のステータスコードが応答された場合、エラー終了します。

ヘッダ

Webhookは、HTTPレスポンスヘッダを参照しません。

メッセージ

Webhookは、HTTPレスポンスボディを参照しません。