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するデータのサイズは、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レスポンスボディを参照しません。