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_id string MTAが発行するメール毎の内部ユニークID
timestamp number イベントが発生した時刻のunix timestamp
email string 宛先アドレス
from string MTAが自動的に生成したenvelope-fromのアドレス
custom_args object APIでメール毎に設定したcustom_argsの内容
event string 発生したイベント
batch_id string APIで指定したbatch_id
header_from string APIで指定したヘッダFROMアドレス

トラッキング関係のイベント（Opened/Clicked）の場合、下記の情報も併せて含められている。

項目名
型
説明
tracking_id string

一意に定められたトラッキング情報毎のユニークID
beacon boolean 開封（ビーコン）の場合はtrue、そうでない場合はfalse
url string 対応する元のリンク先URL
ビーコンの場合は beacon と記載されている
mark string
  • 開封の場合は beacon
  • テキストパートのURLの場合は text
  • HTMLパートのURLの場合は html
ip_address string アクセス元のIPアドレス
user_agent string アクセス元のユーザーエージェント

対応するイベントの種類

管理画面での名称
イベント名
対応配信
説明
送信成功 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_ERROR DNSによる名前解決失敗を原因としてSMTP接続できなかった場合のエラー
TOO_MANY_RECIPIENT SMTP接続内で、宛先メールサーバの送信対象アドレスの上限数を超えた場合のエラー
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アドレスによる接続を許可する設定が必要。

  • 202.218.77.137
  • 202.218.77.138
  • 202.218.77.139
  • 202.218.77.140

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