Webhookを設定する

公開日: 2026年7月16日 · 最終更新日: 2026年9月12日 · 著者 Marcus Biel

この記事のポイント

MaildroppaのWebhook設定を解説します。エンドポイントの作成、イベントの選択、安全なヘッダーの追加、署名検証、配信テスト、再試行の確認、イベントの再送まで、手順を紹介します。

Webhookを使うと、アカウント内で重要なイベントが発生した際に、Maildroppaから別のアプリケーションに通知を送信できます。

購読者の作成、更新、配信停止、タグの付与があったかどうかをMaildroppaに繰り返し問い合わせる必要はありません。イベントの発生後まもなく、アプリケーションでHTTPSリクエストを受信できます。

「Webhooks」ページでは、アカウント全体に適用されるこの連携を一元管理できます。複数のエンドポイントの作成、各エンドポイントが受信するイベントの選択、認証ヘッダーの追加、接続テスト、送信試行の確認、必要に応じた本番イベントの再送が可能です。

Webhook：Webhooksページ全体

アカウントWebhookの仕組み

アカウントWebhookは、次の流れで動作します。

購読者の作成などのイベントがMaildroppaで発生します。
Maildroppaが、そのイベントを受信対象に設定している有効なエンドポイントをすべて確認します。
該当するエンドポイントごとに、1件の配信を作成します。
アカウントのWebhook署名シークレットを使って、JSONペイロードに署名します。
保存済みのエンドポイントURLに、HTTPSのPOSTリクエストを送信します。
エンドポイントが署名を検証し、イベントを保存または処理して、HTTPレスポンスを返します。
Maildroppaが結果を配信履歴に記録し、一時的な失敗の場合は自動的に再試行します。

複数のエンドポイントが同じイベントを受信対象にしている場合、それぞれに個別の配信が行われます。元となる業務上のイベントのEvent IDは共通ですが、各配信には固有のDelivery IDが割り当てられます。

アカウントWebhookは、Automation内の「Send a webhook」ステップとは異なります。アカウントWebhookは、Maildroppa全体で発生する、選択されたアカウントイベントを監視します。一方、AutomationのWebhookは、購読者がその特定のステップに到達したときにのみ送信されます。どちらもアカウントのWebhook署名シークレットを使うため、シークレットをローテーションすると、Maildroppaの署名を検証するすべてのWebhook受信先に影響します。

Webhooksページを開く

「Settings」を開き、「Developers」を展開して「Webhooks」を選択します。

ページは主に次の3つの領域で構成されています。

Signing secret：署名シークレット
Endpoints：エンドポイント
Delivery history：選択したエンドポイントの配信履歴

エンドポイントが複数ある場合は、確認したいエンドポイントの行を選択すると、その配信履歴が表示されます。どの行も選択していない場合は、一覧の先頭にあるエンドポイントの履歴が表示されます。

エンドポイントを作成する前に

Maildroppaを設定する前に、サーバー側の受信処理を準備してください。受信処理は、次の要件を満たす必要があります。

公開HTTPS URLでアクセスできること。
application/jsonのボディを含むPOSTリクエストを受け付けること。
Maildroppaの署名検証が終わるまで、生のリクエストボディをそのまま保持すること。
イベントを安全に受け入れた後にのみ、2xxステータスを返すこと。
Event IDを使い、同じ配信を繰り返し受信しても処理結果が変わらないよう、冪等性を確保すること。
リクエスト中に時間のかかる処理を行わず、速やかに応答すること。

信頼性を確保するには、リクエストを検証し、Event IDとペイロードを永続キューまたはデータベースに保存してから、200または204を返し、その後で業務処理を実行する方法が有効です。

開発用コンピューター、ローカルネットワークのアドレス、保護されていないスクリプトを、本番用のWebhook受信先として公開しないでください。Maildroppaは公開HTTPSの送信先のみを受け付け、配信時にも送信先を再確認します。

ステップ1：署名シークレットを生成する

MaildroppaのWebhookリクエストには、すべて署名が付けられます。受信側では署名シークレットを使って、リクエストがMaildroppaによって作成されたことと、通信中にボディが変更されていないことを検証します。

ページ上部の「Signing secret」パネルには、次のいずれかの状態が表示されます。

Missing — 署名シークレットがまだありません。
Ready — 署名シークレットが設定されています。
Loading — Maildroppaが現在の状態を取得しています。

状態が「Missing」の場合は、「Generate secret」をクリックします。

新しいシークレットがすぐに表示されます。値はwhsec_で始まります。「Copy」をクリックし、受信処理で使用するシークレットマネージャー、または保護された環境設定に保存してください。

シークレットの値全体が表示されるのは、生成またはローテーションの直後だけです。ページを再読み込みするか、別のページに移動すると、シークレットの有無と最終更新日時のみが表示されます。保存済みのシークレットを再表示することはできません。

Webhook：新しく生成した署名シークレット

シークレットを紛失した場合

受信側で現在のシークレットを利用できなくなった場合は、「Rotate secret」をクリックし、新しく表示された値を保存します。

ローテーションすると、以前のシークレットは即座に置き換えられます。移行期間として新旧両方の値が保持されることはありません。追加のテストを送信する前や、本番配信を利用する前に、このアカウントのシークレットを使うすべての受信処理を更新してください。

新規配信、スケジュール済みの再試行、テスト、再送には、HTTPリクエスト時点のシークレットで署名が付けられます。そのため、ローテーション前に作成された配信でも、送信試行がローテーション後であれば、新しいシークレットが使われます。

シークレットはパスワードと同様に管理する

署名シークレットを、ブラウザ側のコード、公開リポジトリ、URL、エラーページ、通常のアプリケーションログに記載しないでください。

シークレットが必要なのは、サーバー側の受信処理だけです。漏えいの可能性がある場合は、直ちにローテーションし、すべての受信処理を更新してください。

Webhookの署名を検証する

各リクエストには、次のMaildroppaヘッダーが含まれます。

X-Maildroppa-Event-Id — 業務上のイベントを識別します。
X-Maildroppa-Delivery-Id — 個々の配信を識別します。
X-Maildroppa-Timestamp — 署名時刻を秒単位のUnixタイムスタンプで示します。
X-Maildroppa-Signature — バージョン情報を含むHMAC署名です。

次のヘッダーも送信されます。

Content-Type: application/json
User-Agent: Maildroppa-Webhooks/1.0

署名の形式は次のとおりです。

v1=<lowercase hexadecimal HMAC>

Maildroppaは、HMAC-SHA256で署名を生成します。署名対象は、タイムスタンプ、ピリオド、改変していない生のJSONリクエストボディを、この順に連結した内容です。

<timestamp>.<raw request body>

HMACキーには署名シークレットを使用します。

次のNode.jsの例は、検証の中核となる処理を示しています。rawBodyには、解析後に再シリアライズしたJSONではなく、元のリクエストのバイト列を使う必要があります。

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

署名を検証した後は、タイムスタンプとサーバー時刻も比較します。インフラ環境に応じて、例えば5分といった短い許容時間を設定し、その範囲を外れるリクエストは拒否してください。これにより、傍受された有効なリクエストが、かなり時間を置いてから再送されるリスクを軽減できます。

両方の検証に合格してから、JSONを解析して処理してください。

署名エラーの主な原因

署名の検証に失敗する原因は、通常、次のいずれかです。

ローテーション後も、受信側で古いシークレットを使っている。
署名を計算する前に、ミドルウェアがJSONを解析または変更している。
ボディだけを署名対象とし、<timestamp>.を含めていない。
タイムスタンプにヘッダーの値をそのまま使わず、書式を変えた日付として扱っている。
比較時にv1=のプレフィックスを含めていない。
計算したHMACを、小文字の16進数以外の形式でエンコードしている。

検証に失敗した場合は、Event IDとDelivery IDをログに記録してください。ただし、署名シークレットや機密性の高いカスタムヘッダーの値は、絶対にログに記録しないでください。

ステップ2：エンドポイントを追加する

「Endpoints」セクションで「Add endpoint」をクリックします。

エディターには、次の4つの設定項目があります。

Endpoint URL：エンドポイントURL
Events：イベント
Custom headers：カスタムヘッダー
Active：有効状態

新しいエンドポイントは、初期状態で「Active」が選択され、エディターに表示されるすべてのイベントが受信対象になっています。保存前に選択内容を確認し、受信側で必要な通知だけを受け取るようにしてください。

Webhook：エンドポイント追加ダイアログ

エンドポイントURLを設定する

Maildroppaからのリクエストを受信する、完全な公開URLを入力します。例：

https://integrations.example.com/webhooks/maildroppa

URLは、次の要件を満たす必要があります。

https://を使用すること。
有効な公開ホスト名を含むこと。
2,048文字以内であること。
{または}を使ったテンプレート変数を含まないこと。
ホスト名の前にユーザー名やパスワードを含まないこと。
#で始まるURLフラグメントを含まないこと。
標準のHTTPSポート443を使用すること。
localhost、IPアドレスの直接指定、ブロック対象のプライベートネットワークまたは予約済みネットワークに名前解決されるホスト名を使用しないこと。

クエリパラメータは使用できますが、APIキーなどのシークレットをURLに含めないでください。URLはエンドポイント一覧や配信データに表示されます。認証情報には、代わりにカスタムヘッダーを使用してください。

Maildroppaはリダイレクト先を追跡しません。301、302、307、308を返すURLではなく、最終的なHTTPS送信先を保存してください。

送信前には、送信先ホスト名の名前解決が再度行われます。保存時には有効だったホスト名でも、後からプライベートアドレスやブロック対象のアドレスに解決されるようになった場合は、送信が拒否されます。

イベントを選択する

少なくとも1つのイベントを選択します。エンドポイントが受信するのは、エディターで選択したイベントタイプだけです。

次のイベントを選択できます。

購読者の作成（Subscriber Created） — `subscriber.created`

Maildroppaアカウントで購読者が作成されたときに送信されます。

このイベントを使って、CRM、顧客データプラットフォーム、社内データベースなど、権限を考慮して動作するシステムに対応する連絡先を作成できます。

このイベントの発生だけで、すべての登録においてダブルオプトイン（確認メールによる登録確認）が完了したと判断しないでください。現在の状態は、ペイロード内の購読者ステータスで確認できます。

購読者の更新（Subscriber Updated） — `subscriber.updated`

購読者の標準情報またはカスタム項目の値が変更されたときに送信されます。

ペイロード内の購読者オブジェクト全体を、Maildroppa上の現在の購読者情報として扱ってください。特定のプロパティだけが変更されたとは限りません。

タグの付与と削除には、それぞれ専用のイベントタイプがあるため、個別に処理できます。

購読者の配信停止（Subscriber Unsubscribed） — `subscriber.unsubscribed`

配信停止の操作によって、購読者が配信停止済みの状態になったときに送信されます。

このイベントを使って、連携先のシステムでも該当する連絡先を配信対象から除外してください。別のシステムで有効な連絡先として扱われているからといって、自動的に配信を再開しないでください。

タグの追加（Tag Added） — `subscriber.tag_added`

購読者にタグが付与されたときに送信されます。

ペイロードには、購読者と、今回の変更で付与されたタグが含まれます。

タグの削除（Tag Removed） — `subscriber.tag_removed`

購読者からタグが削除されたときに送信されます。

ペイロードには、更新後の購読者情報と削除されたタグが含まれます。削除されたタグは、購読者の現在のtags配列には含まれませんが、別のデータとして提供されます。

フォームの送信（Form Submitted） — `form.submitted`

訪問者がMaildroppaの登録フォームを送信したときに送信されます。

これはフォームが送信されたことを示す通知であり、ダブルオプトインの完了を示すものではありません。登録確認の完了を前提とするワークフローでは、購読者の現在のステータスと確認プロセスを引き続き考慮する必要があります。

役割が異なる場合はエンドポイントを分ける

イベントの種類に応じて、異なるシステムに送信できます。例：

購読者とタグのイベントをCRMに送信する。
配信停止イベントを配信除外管理サービスに送信する。
フォーム送信イベントを分析パイプラインに送信する。

エンドポイントを分けると、不要な通信が減り、障害の原因も調べやすくなります。各エンドポイントで、受信イベント、URL、カスタムヘッダー、有効状態、テスト、配信履歴を個別に管理できます。

カスタムヘッダーを追加する

カスタムヘッダーは任意です。受信先でAPIキー、ベアラートークン、テナント識別子などの固定ヘッダーが必要な場合に使用します。

「Add header」をクリックし、「Header name」にヘッダー名、「Header value」に値を入力します。設定例：

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

カスタムヘッダーは最大20個まで追加できます。

ヘッダー名の要件：

入力は必須です。
128文字以内で指定します。
HTTPヘッダー名として有効な文字を使います。
大文字と小文字を区別せずに比較したとき、ほかのヘッダー名と重複しないようにします。

ヘッダー値の要件：

入力は必須です。
2,000文字以内で指定します。
改行は使用できません。

次の名前は予約済みのため、カスタムヘッダーで置き換えることはできません。

Content-Type
Content-Length
Host
User-Agent
X-Maildroppa-で始まるすべての名前

この制限により、Maildroppaの配信ヘッダーや署名ヘッダーが、カスタム値で置き換えられることを防ぎます。

ヘッダーに含まれるシークレットの保存方法

Maildroppaは、カスタムヘッダーの値を暗号化してから保存します。保存済みの値が、読み取れる形式でブラウザに返されることはありません。

後でエンドポイントを編集すると、値の欄には「Stored value kept」と表示されます。既存のシークレットを変更しない場合は、空欄のままにしてください。置き換える場合は、新しい値を入力します。

ヘッダー名を変更した場合は、値も再入力してください。保存済みのシークレットが保持されるのは、元のヘッダー名を変更しない場合だけです。

ヘッダーの行を削除すると、エンドポイントの保存後、そのヘッダーは以後の配信に含まれなくなります。

カスタムヘッダーの値は、保存されるリクエスト情報の中でも機密情報として扱われます。配信履歴ではマスクされ、実際の値は表示されません。

エンドポイントを有効・無効にする

すぐにイベントを受信できる状態であれば、「Active」を選択したままにします。

配信を開始せずに設定だけを保存したい場合は、選択を解除します。後からエンドポイント一覧で有効にできます。

無効なエンドポイントは、次のように扱われます。

新しく発生したイベントは受信しません。
テストWebhookは送信できません。
引き続き表示・編集できます。
既存の配信履歴は引き続き確認できます。

エンドポイントを有効にしても、無効だった間に発生したイベントが遡って配信されることはありません。

URL、イベントの選択、ヘッダー、有効状態が正しいことを確認したら、「Save」をクリックします。

エンドポイント一覧の見方

各エンドポイントの行には、次の情報が表示されます。

送信先URL。
ActiveまたはInactiveのバッジ。
受信対象のイベントタイプ。
カスタムヘッダーの数。
エンドポイントの最終更新日時。

次の操作が可能です。

On/Off — エンドポイントを有効・無効に切り替えます。
Test — 有効なエンドポイントに、テストリクエストを1件すぐに送信します。
Edit — URL、イベント、ヘッダー、有効状態を変更します。
Delete — 確認後、エンドポイントの設定を完全に削除します。

行の主要部分を選択すると、一覧の下にそのエンドポイントの配信履歴が表示されます。

Webhook：有効なエンドポイントの行

設定変更が既存の配信に与える影響

アカウントイベントが発生すると、その時点のエンドポイントURL、ペイロード、カスタムヘッダーのスナップショットを含む配信が作成されます。

URLやカスタムヘッダーの変更は、新しく作成される配信に適用されます。すでにキューに入っている配信では、元の送信先と保存済みのヘッダー設定が保持されます。

受信イベントの選択を変更した場合も、変更後に発生するイベントにのみ適用されます。イベントの発生時に選択されていなかったイベントタイプについて、遡って配信が作成されることはありません。

署名シークレットは扱いが異なり、HTTPリクエストの準備時に読み込まれます。そのため、保留中の配信や再送では、ペイロードとエンドポイントのスナップショットが以前に作成されたものであっても、ローテーション後の新しい署名シークレットが使われる場合があります。

エンドポイントをテストする

受信処理と署名シークレットの準備ができたら、有効なエンドポイントの「Test」をクリックします。

保存済みのエンドポイントURLとカスタムヘッダーを使い、署名付きリクエストが1件すぐに送信されます。エディターを開いていても、未保存の変更はテストに反映されません。

テストペイロードでは、イベントタイプにwebhook.testを使用し、livemodeをfalseに設定します。

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

生成されるIDとタイムスタンプは、実際のテストごとに異なります。

テストのHTTP送信試行は1回だけです。テスト配信は本番用の再試行スケジュールには登録されず、再送もできません。

リクエストが完了すると、結果パネルに次の情報が表示されます。

Test successまたはTest failed：テストの成否
Event ID
HTTPステータス：レスポンスを受信した場合
所要時間
Delivery ID
エラー情報：取得できた場合
レスポンスの抜粋：受信先がボディを返した場合

テストは「Delivery history」にも「Test」バッジ付きで表示されます。テストリクエストだけを表示するには、「Test」フィルターを使用します。

Webhook：成功したテスト配信

本番ペイロードの構造

本番のアカウントイベントは、共通のJSONエンベロープを使用します。

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

トップレベルの各プロパティは、次の内容を表します。

id — Event IDです。X-Maildroppa-Event-Idと一致します。
type — エンドポイントのエディターで選択したイベントキーです。
schema_version — ペイロードのスキーマバージョンです。イベントの解析方法を判断する際に使用します。
created_at — イベントのペイロードが作成された時刻です。UTCで示されます。
livemode — 本番イベントではtrue、テストイベントではfalseです。
data — イベント固有の内容です。

typeの値を完全一致で判定し、イベントを振り分けてください。連携に不要な追加プロパティは無視し、互換性を保ったペイロードの拡張によって受信処理が動作しなくなることを防ぎます。

購読者イベントのペイロード

購読者イベントには、data.subscriber内に現在の購読者情報が含まれます。

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fieldsとtagsは配列で、空の場合もあります。また、値がない購読者プロパティはnullになることもあります。任意のプロフィール項目がすべて存在すると想定せず、ペイロードのスキーマに従って処理してください。

タグイベントのペイロード

タグイベントには、購読者と、イベントの発生原因となったタグの両方が含まれます。

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

subscriber.tag_removedでは、購読者の現在のtags配列に削除済みのタグが含まれていなくても、data.tagでそのタグを識別できます。

Event ID、Delivery ID、冪等性

Event IDとDelivery IDは、用途が異なります。

Event ID

Event IDは、業務上のイベントを識別します。次の場所に表示されます。

ペイロードのトップレベルにあるidプロパティ。
X-Maildroppa-Event-Idリクエストヘッダー。
配信履歴。

同じイベントが、そのイベントを受信対象にしている複数のエンドポイントに送信されることがあります。これらの配信ではEvent IDが共通です。

再試行や手動再送でも、元のEvent IDが保持されます。処理済みのEvent IDを保存し、業務処理の冪等性を確保してください。これにより、リクエストを繰り返し受信しても、連絡先の重複作成、取り消せない処理の再実行、同じ変更の2重適用を防げます。

Delivery ID

Delivery IDは、1件の配信レコードを識別します。次の場所に表示されます。

X-Maildroppa-Delivery-Idリクエストヘッダー。
配信履歴。

各エンドポイントへの配信には、固有のDelivery IDがあります。手動再送では新しいDelivery IDが作成されますが、元のEvent IDは保持されます。

技術的な追跡やサポート対応にはDelivery IDを、業務処理の重複排除にはEvent IDを使用してください。

適切なHTTPレスポンスを返す

Maildroppaは、レスポンスを次のように分類します。

2xxレスポンスは、すべて配信成功として扱います。
408 Request Timeout、429 Too Many Requests、5xxレスポンスは一時的な失敗として扱い、再試行する場合があります。
一時的な可能性があるネットワーク障害は、再試行します。
リダイレクトやその他の3xxレスポンスは追跡せず、再試行せずに終了する失敗として扱います。
その他の4xxレスポンスは、再試行せずに終了する失敗として扱います。

200、202、または204を返すのは、イベントを安全に受け入れた場合だけにしてください。処理に時間がかかる場合は、先にイベントを保存して成功レスポンスを返し、時間のかかる処理を後から非同期で実行します。

別のWebhook URLへのリダイレクトは返さないでください。最終的なURLをMaildroppaに設定してください。

自動再試行のスケジュール

本番配信では、HTTP送信を最大7回試行します。

再試行可能な失敗が発生すると、次の待機時間で次回の試行がスケジュールされます。

試行1の後：1分
試行2の後：5分
試行3の後：30分
試行4の後：2時間
試行5の後：12時間
試行6の後：24時間

試行7でも再試行可能な失敗が発生した場合、配信は「Dead」になり、それ以降の自動試行はスケジュールされません。

待機時間は、それぞれの試行が失敗した時点から計測されます。配信は非同期で処理され、システム保護のための制限も適用されるため、実際の配信時刻は多少遅れる場合があります。

受信先の一時的な問題は、できるだけ「Next retry」に表示される時刻までに解消してください。自動試行が終了している場合は、受信先が復旧してから「Replay」で再送します。

配信履歴の見方

「Delivery history」には、現在選択しているエンドポイントの配信履歴が表示されます。セクションの見出しにエンドポイントURLが表示されるため、どのエンドポイントの履歴かを確認できます。

次のフィルターを使用できます。

All — 本番配信とテスト配信を表示します。
Production — 本番イベントの配信だけを表示します。
Test — 手動テストだけを表示します。

最新の状態を取得するには、「Refresh」をクリックします。Maildroppaが配信や再試行を行う間、履歴を開いたままにする必要はありません。

ページには、選択したフィルターに一致する最新50件の配信が表示されます。

Webhook：配信履歴のフィルター

配信履歴の列

各行には、次の情報が表示されます。

Created — 配信レコードの作成日時。
State — Pending、Success、Failed、Deadのいずれかの状態。
HTTP — レスポンスステータス、試行回数、所要時間、該当する場合は次回の再試行時刻。
Subscriber — イベントが購読者に関連する場合、その購読者のメールアドレス。
Delivery — イベントタイプ、Event ID、Delivery ID。
Actions — 再送可能な配信の場合はReplay。

HTTPリクエストが送信されていない場合、HTTP列には「No HTTP attempt」と表示されます。これは、署名シークレットがない、保存済みの送信先を安全に使用できなくなったなどの理由で、送信前にMaildroppaがリクエストを拒否した場合に起こります。

情報を取得できた場合は、行にエラーと受信先からのレスポンスの抜粋も表示されます。Webhookのレスポンスボディには、シークレットや機密性の高い個人データを含めないでください。レスポンスの一部が、アカウントの配信ログに表示される可能性があります。

配信の状態

Pendingは、初回の試行またはスケジュール済みの再試行を待っている状態です。次の試行がスケジュールされている場合は、「Next retry」が表示されます。

Successは、受信先が2xxレスポンスを返した状態です。それ以降の自動試行は不要です。

Failedは、再試行できない問題で配信が終了した、HTTP送信の試行前にリクエストが拒否された、または送信前に配信が停止された状態です。

Deadは、再試行可能な問題に対してすべての自動試行を行っても、成功レスポンスを受信できなかった状態です。

履歴の保持期間

配信レコードの保持期間は、次のとおりです。

成功した本番配信：30日
失敗した本番配信：90日
Deadになった本番配信：90日
テスト配信：30日

より長期間の監査履歴が必要な場合は、連携のログを独自に保存してください。Event IDとDelivery IDを保存し、シークレットを不必要に保存することは避けてください。

配信を再送する

完了した本番配信をもう一度試行するには、「Replay」をクリックします。

再送できるのは、「Success」「Failed」「Dead」のいずれかの状態にある本番配信です。「Pending」の配信やテスト配信は再送できません。

再送では、次の処理が行われます。

新しいPending状態の配信を作成します。
新しいDelivery IDを作成します。
元のEvent IDを保持します。
元のイベントタイプとJSONペイロードを保持します。
保存済みの元の送信先URLとカスタムヘッダーのスナップショットを使用します。
新しいリクエストの準備時点の署名シークレットを使用します。

再送時に、購読者の現在のデータからペイロードが再構築されることはありません。元のイベントのスナップショットがそのまま再送されます。これにより、再送内容を監査でき、過去のイベントの意味が知らないうちに変わることを防げます。

同じ元の配信に対して、同時にPending状態にできる再送は1件だけです。追加の再送を要求する前に、先の再送が完了するまで待ってください。

再送前に、エンドポイントが有効であることを確認してください。無効な場合、キューに入った再送は正常に配信されません。

Maildroppaが成功レスポンスを受信できなかった場合でも、受信先では業務処理が完了している可能性があります。そのため、再送は重複リクエストになることがあります。Event IDで重複を排除することで、連携先のシステムで同じ処理が繰り返されるのを防げます。

エンドポイントを編集する

URL、受信イベント、カスタムヘッダー、有効状態を変更するには、「Edit」をクリックします。

保存前の確認事項と操作は、次のとおりです。

新しいURLがすでに利用可能であることを確認します。
保存済みのヘッダー値を変更しない場合は、その値の欄を空欄のままにします。
名前を変更したすべてのヘッダーに、新しい値を入力します。
必要な通知の選択を誤って解除していないか、受信イベントを確認します。
保存し、新しいテストWebhookを送信します。

キューに入っている配信では、既存のURLとカスタムヘッダーのスナップショットが保持されます。新しい設定が古いキュー内のリクエストにも適用されるとは考えず、今後の配信を対象としてテストしてください。

エンドポイントを無効にする

設定や履歴を削除せずに連携を一時停止するには、「On/Off」スイッチを使用します。

エンドポイントを「Off」にすると、次のように動作します。

新しいイベントは、そのエンドポイントの配信キューに追加されなくなります。
保留中の配信のうち、送信処理の対象としてまだ取得されていないものは、Failedになります。
Testが無効になります。
エンドポイントは引き続き編集でき、後から再び有効にできます。

無効にした時点ですでに進行中のリクエストは、そのまま完了する場合があります。この違いが連携に影響する場合は、「Off」に切り替えた後で配信履歴を確認してください。

無効だった間に受信できなかったイベントは、再び「On」にしても遡って配信されません。

エンドポイントを削除する

エンドポイントが不要になった場合は、「Delete」をクリックし、警告を確認して削除を確定します。

削除すると、エンドポイントがページから消え、今後のイベント配信が停止します。また、保留中の配信のうち、送信処理の対象としてまだ取得されていないものは失敗となります。

一時停止のために削除しないでください。設定や表示可能な履歴が後から必要になる可能性がある場合は、「On/Off」スイッチを使用します。

削除前に、連携の監査に必要なEvent IDやDelivery IDを記録してください。

トラブルシューティング

エンドポイントを保存できない

次の点を確認してください。

URLがhttps://で始まっていること。
URLが公開ホスト名とポート443を使用していること。
URLに変数、ログイン情報、フラグメントが含まれていないこと。
少なくとも1つのイベントが選択されていること。
すべてのカスタムヘッダーに、重複しない名前と値が設定されていること。
MaildroppaやHTTPの予約済みヘッダー名を、カスタムヘッダー名に使用していないこと。

Testが無効になっている

「Test」は、有効なエンドポイントでのみ使用できます。エンドポイントを「On」にするか、編集画面で「Active」を選択し、保存してからテストしてください。

テストでNo HTTP attemptと表示される

署名シークレットの状態が「Missing」の場合は、シークレットを生成してください。また、送信先のホスト名が公開されており、現在も正しく名前解決されるかを確認してください。

シークレット、URL、カスタムヘッダーが無効な場合や、送信先の安全性チェックに合格しない場合は、送信前にリクエストが拒否されることがあります。

受信先が`401`または`403`を返す

保存済みのカスタムヘッダー名と認証情報を確認してください。変更されている場合は、エンドポイントを編集して値を再入力します。

受信側で、独自のAPI認証情報とMaildroppaの署名を混同していないかも確認してください。カスタムの認証ヘッダーとX-Maildroppa-Signatureは用途が異なり、それぞれ独立して検証できます。

受信先がリダイレクトを返す

Maildroppaはリダイレクト先を追跡しません。エンドポイントURLを最終的な公開HTTPS URLに置き換え、再度テストしてください。

署名が一致しない

受信処理について、次の点を確認してください。

現在の署名シークレットを使用していること。
X-Maildroppa-Timestampの値をそのまま使用していること。
<timestamp>.<raw request body>を署名対象にしていること。
HMAC-SHA256を使用し、結果を小文字の16進数で出力していること。
v1=を含む完全な値を比較していること。
JSONの解析でボディが変更される前に比較していること。

同じイベントが複数回届く

ネットワークの中断、再試行、手動再送の後に起こることがあります。Webhook配信システムでは、「正確に1回」ではなく「少なくとも1回」の配信方式を採用するのが一般的です。

Event IDを冪等性キーとして使用してください。処理済みのEvent IDを再度受信し、追加の処理が不要な場合は、2xxレスポンスを返します。

配信がPendingになっている

HTTP列の「Next retry」を確認してください。再試行可能な408、429、5xx、または一時的なネットワーク障害が発生した場合、配信は次の試行予定時刻までPendingのままです。

再試行時刻を過ぎたら、「Refresh」をクリックして最新の状態を取得してください。

配信がDeadになっている

すべての自動試行が終了しています。まず受信側の問題を解消し、エンドポイントが有効であることを確認して、テストWebhookを送信してください。その後、本番配信の「Replay」で再送します。

本番運用前の推奨チェックリスト

本番でエンドポイントを利用する前に、次のすべてを確認してください。

受信先が、有効な証明書を備えた安定した公開HTTPS URLを使用している。
署名シークレットをソースコードの外部に保存している。
改変していない生のボディを使って署名を検証している。
文書化した許容時間に従って、古いタイムスタンプのリクエストを拒否している。
受信側でEvent IDを保存し、重複を排除している。
追跡用にEvent IDとDelivery IDをログに記録している。
時間のかかる処理は、イベントを永続的に保存して受け入れた後に実行している。
受け入れたイベントに対してのみ、2xxレスポンスを返している。
独自の認証情報をURLではなくヘッダーに保存している。
必要なイベントタイプだけを選択している。
テストWebhookが成功し、配信履歴にも正しく表示されている。
本番配信でエラーが発生し始めたときに通知を受け取れるよう、監視を設定している。

これらの対策を整えることで、Webhooksページを通じて、信頼性の高い連携に必要な2つの要素を確保できます。アプリケーションへの安全なイベント配信と、Maildroppa内で確認できる明確な運用履歴です。

目次

メール配信ツールで メールマーケティングを シンプルに