Webhook

概要

autobahn MTAを利用したメール送信、メールの送信成功、バウンス受信等の各種イベントが発生した場合に、任意のサーバに通知するWebhookのリクエスト内容を記述する機能です。

ボディの署名

Webhookには署名キーが設定されており、通知されるボディの文字列に対して署名キーを用いて HMAC(SHA1)で署名し、Base64でエンコードした文字列をリクエストヘッダに含めています。
署名キーは、autobahn MTAのAPI又はダッシュボードで取得することができます。
 
ヘッダ名は、X-Autobahn-Webhook-Signatureという名前となっており、値は下記の形式です。
  • [署名キーのsha256ハッシュ].[HMAC(SHA1)の署名]
この署名の正当性を検証することで、Webhookのリクエストがautobahn MTAからのものかを判定することができます。

署名検証のサンプル(PHP)

<?php
$body = file_get_contents('php://input');                      // Webhookリクエストのボディを取得
$signature = $_SERVER['HTTP_X_AUTOBAHN_WEBHOOK_SIGNATURE'];    // リクエストヘッダから署名結果を取得
$key = "this is signature key";                                // API等で取得した署名キー
$signed = explode('.', $signature)[0];                         // 署名キーのハッシュ
$signature = explode('.', $signature)[1];                      // 署名


$hash = hash_hmac('sha1', $body, $key, true);                  // リクエストボディをHMACのsha1で署名
$hash = base64_encode($hash);                                  // Base64エンコード


$result = $hash === $signature ? "MATCHED!" : "UNMATCHED...";  // ヘッダの署名とリクエストボディ及び署名キーから算出した署名が一致しているかどうか


var_dump($result);

メールイベント

Webhookのリクエストは、HTTPメソッドがPOST、ボディの形式はjsonフォーマットとなっています。
Webhookの一度のリクエストに含まれるデータの数は1件のみです。
[
  {
    "mta_mail_id":"99999999999999999999",
    "email": "someone@example.com",
    "from": "from@example.net",
    "timestamp": 1337969592,
    "custom_args": {
      "user_id": "1234"
    },
    "event": "Delivered",
    "batch_id": "A0001",
    "header_from": "header@example.org"
  }
]
 
項目名
型
説明
mta_mail_idstringMTAが発行するメール毎の内部ユニークID
timestampnumberイベントが発生した時刻のunix timestamp
emailstring宛先アドレス
fromstringMTAが自動的に生成したenvelope-fromのアドレス
custom_argsobjectAPIでメール毎に設定したcustom_argsの内容
eventstring発生したイベント
batch_idstringAPIで指定したbatch_id
header_fromstringAPIで指定したヘッダFROMアドレス
トラッキング関係のイベント(Opened/Clicked)の場合、下記の情報も併せて含みます。
 
項目名
型
説明
tracking_idstring
一意に定められたトラッキング情報毎のユニークID
beaconboolean開封(ビーコン)の場合はtrue、そうでない場合はfalse
urlstring対応する元のリンク先URL
ビーコンの場合はbeaconと記載される
markstring
  • 開封の場合はbeacon
  • テキストパートのURLの場合はtext
  • HTMLパートのURLの場合はhtml
ip_addressstringアクセス元のIPアドレス
user_agentstringアクセス元のユーザーエージェント

対応するイベントの種類

管理画面での名称
イベント名
対応配信
説明
送信成功Delivered
  • API
  • SMTPリレー
外部サーバがメールを受け付けた際に発生するイベント
文面生成Processed
  • API
APIが受け取ったメールリクエストを元に、メール文面を生成した時点で発生するイベント
バウンスBounced
  • API
  • SMTPリレー

外部サーバがメール送信時に500系のエラーを返してきた際、もしくは一旦外部サーバがメールを受け付けた後にバウンスメールを送信してきた際に発生するイベント
 

  • custom_args項目にSMTPレスポンスもしくはバウンスメールを解析して判定したバウンス理由を表すbounce_reason項目が付与される
  • custom_argsに同名の項目が存在している場合は、システムによって値が上書きされる
配信停止Dropped
  • API
  • SMTPリレー
配信停止アドレス宛へのメール送信を試みた際に発生するイベント

文面生成・SMTPリレー・ブラックリストとは排他の関係
スパムSpam Report
  • API
  • SMTPリレー
外部サーバがメール送信時にスパム判定として拒否応答を返してきた際、もしくは一旦外部サーバがメールを受け付けた後にスパムとして判定した旨が記載されたバウンスメールを送信してきた際に発生するイベント

バウンスの特殊なケースとして見なしており、バウンスとは排他の関係
メール開封Opened
  • API
トラッキング情報を付与したメールが開封された際に発生するイベント
URLクリックClicked
  • API
トラッキング情報を付与したメールがのリンクがクリックされた際に発生するイベント
ブラックリストBlacklisted
  • API
  • SMTPリレー
ブラックリストアドレス宛へのメール送信を試みた際に発生するイベント

文面生成・SMTPリレー・配信停止とは排他の関係
SMTPリレーRelayed
  • SMTPリレー
SMTPリレーで受け取ったメールを元に、メール文面を生成した時点で発生するイベント
(WebhookイベントのProcessed に相当する。)

バウンス理由

[
  {
    "mta_mail_id":"99999999999999999999",
    "email": "someone@example.com",
    "from": "from@example.net",
    "timestamp": 1337969592,
    "custom_args": {
      "bounce_reason": "USER_UNKNOWN"
    },
    "event": "Bounced",
    "batch_id": "A0001",
    "header_from": "header@example.org"
  }
]

対応するイベントの種類

bounce_reason
理由
NETWORK_ERRORDNSによる名前解決失敗を原因としてSMTP接続できなかった場合のエラー
TOO_MANY_RECIPIENTSMTP接続内で、宛先メールサーバの送信対象アドレスの上限数を超えた場合のエラー
HAS_MOVEDメールボックスが別のメールボックスに移動したが、自動でメールが転送されない場合のエラー
FILTEREDユーザがメールの受信を拒否している場合のエラー
TOO_MANY_CONNECTION先メールサーバの同時接続数を超過した場合のエラー
MAILBOX_FULL宛先のメールボックスが一杯で受信できなかった場合のエラー
HOST_UNKNOWN宛先メールアドレスのドメインが無効なドメインだった場合のエラー
SUSPENDED宛先メールアドレスのユーザアカウントが無効な場合のエラー
USER_UNKNOWN宛先メールアドレスのローカルパートに該当するユーザが存在しない場合のエラー
NO_RELAYING宛先メールサーバからSMTPリレーを拒否された場合のエラー
SYNTAX_ERROR宛先メールサーバがSMTPコマンドを認識できなかった場合のエラー
SECURITY_ERROR宛先メールサーバがセキュリティ上の理由やポリシー違反で受信拒否した場合のエラー
NOT_ACCEPT宛先メールサーバが先方都合によりメールを受信できなかった場合のエラー
REJECTED宛先メールサーバが具体的な理由を開示せずに受信拒否した場合のエラー
BLOCKED
宛先メールサーバに接続した際に、発信元メールサーバのIPアドレスやホスト名、
またはEHLO/HELOコマンドの値によって接続が拒否された場合のエラー
SYSTEM_FULL宛先メールサーバのディスクが一杯になった場合のエラー
EXCEED_LIMIT宛先メールサーバのメール受信量が限界値を超えた場合のエラー
MAILER_ERROR宛先メールサーバ上でプログラムが正常終了しなかった場合のエラー
SYSTEM_ERROR宛先メールサーバ内でLDAPサーバへの接続失敗などのシステムエラーが発生した場合のエラー
SPAM_DETECTED送信したメールがスパムとして検出された、あるいはDNSBLによってスパム送信ホストとして認識された場合のエラー
EXPIRED送信したメールが宛先メールサーバに接続できないなどの理由で配送時間切れになった場合のエラー
CONTENT_ERROR送信したメールの形式が宛先メールサーバで変換できない、もしくは処理できない形式だった場合のエラー
MESSAGE_TOO_BIG送信したメールの文面サイズが宛先メールサーバの許容量を超えた場合のエラー
UNKNOWNバウンス解析理由を特定できなかった場合のエラー

受信側サーバーのIPアドレス接続制限のためのホワイトリスト

Webhookを受信するサーバーでIPアドレスの接続制限を設ける場合、下記のIPアドレスによる接続を許可する設定が必要です。
  • 13.113.132.92
  • 52.69.47.118

デモ環境利用時は以下のIPアドレスを許可してください

  • 13.231.19.160
※ 接続許可が必要なIPアドレスは、告知の上変更する場合があります。