Webhook
Webhookはメールの送信または受信で発生するイベントを、指定されたエンドポイントにHTTPでポストするインターフェイスを提供します。
バージョン
POSTパラメータや応答メッセージのフォーマットはAPIのバージョンによって異なります。利用するバージョンのAPI仕様を参照ください。
現在のバージョンは2です。
バージョン1のAPI仕様はこちらを参照ください。
共通仕様
このセクションでは、Webhookの共通仕様について説明します。
| 項目 | 値 |
|---|---|
| プロトコル | HTTPS |
| 文字コード | UTF-8 |
| 改行コード | LF |
エンドポイント
エンドポイントとは、HTTPリクエストを受信するURLを指します。
Webhookは、お客様が実装し、管理GUIに設定したエンドポイントに対して、メール配信状況や、メール受信などのイベントデータをポストします。
認証
Webhook が送信するHTTPリクエストに対して、BASIC認証またはAPIキーを使用した認証機能をエンドポイント側で実装することができます。
HTTPリクエスト
このセクションでは、Webhook が送信するHTTPリクエストの仕様について説明します。
バージョン
Webhook のHTTPリクエストは以下のバージョンに対応しています。
| 項目 | 対応状況およびバージョン |
|---|---|
| SSL/TLSのバージョン | TLS1.1, TLS1.2をサポートしています。 |
| HTTPのバージョン | HTTP/1.1をサポートしています。 |
メソッド
Webhook は、POSTメソッドのみを送信します。
ヘッダ
Webhook は、以下のヘッダフィールドを送信します。
| ヘッダフィールド | 説明 |
|---|---|
| content-length | POSTデータのサイズ |
| content-type | POSTデータのコンテンツタイプ。下記MIMEタイプを参照。 |
| host | POST先サーバーのホスト名とポート番号（例:endpoint.example.com:443） |
| connection | Keep-Alive |
| user-agent | 文字列 HttpClient を送信します。 |
| accept-encoding | gzip, deflate |
| authorization | BASIC認証のためのユーザ認証用データや Bearer トークンを送信します。 |
MIMEタイプ
エンドポイントはエンコードタイプに応じて適切にHTTPリクエストを取り扱う必要があります。
メール配信状況を通知するEvent Webhookのエンコードタイプは、application/x-www-form-urlencoded です。管理コンソールの設定で「JSON形式を使用する」を設定することで、application/json を使用することができます。
メール受信を通知する Inbound Webhook のエンコードタイプは、multipart/form-data です（添付ファイルを取り扱うため）。管理コンソールの設定で「JSON形式を使用する」を設定することで、application/json を使用することができます。
注意
Inbound Webhook で application/json を使用する場合、メールの添付ファイルは通知されません。
パラメータ
Webhook は全てのHTTPリクエストに、認証を行うための api_key を含め、イベントごとに定義されたパラメータを送信します。
このドキュメントは以下フォーマットに従い、パラメータの説明を記述します。
| パラメータ | 必須 | データ型 | 説明 |
|---|---|---|---|
| api_key | Yes | ASCII | 認証に使用するシークレットキー |
| server_composition | Yes | UTF-8 | 操作対象となるサーバ構成の名称(サーバ構成についてはこちらを参照) |
- パラメータ：POSTするパラメータの名前。
- 必須：このパラメータが必須である場合、Yes。
- データ型：パラメータ値のデータ型。（後述、データ型を参照）
- 説明：このパラメータに関する説明。
デフォルト値、値の範囲などの制限があるパラメータについては、説明欄に以下の書式で記載します。
- デフォルト：(デフォルト値)
- 範囲：min=(最小値) / max=(最大値)
- 制約：パラメータに関する制約の記述。
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, 503, 504が応答された場合、エンドポイントまたはリバースプロキシの一時的なエラーとして判断し、イベントの再送を試みます。それ以外の500番台のステータスコードが応答された場合、エラー終了します。 |
ヘッダ
Webhookは、HTTPレスポンスヘッダを参照しません。
メッセージ
Webhookは、HTTPレスポンスボディを参照しません。