Webhookを設定する

Published: 2026年7月16日 · Last updated: 2026年7月21日 · By Marcus Biel

In brief

MaildroppaでアカウントWebhookを設定する方法を解説。安全な公開HTTPSエンドポイントの作成、イベント選択、カスタムヘッダー、署名シークレットの管理と検証、テスト、配信履歴、再試行、再送、イベントIDによる重複防止、応答コードやトラブルシューティングを紹介します。

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

購読者が作成、更新、購読解除されたか、タグが付与されたかをMaildroppaに繰り返し問い合わせる代わりに、イベント発生後すぐにアプリケーションでHTTPSリクエストを受信できます。

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

Webhook: Webhookページ全体

アカウントWebhookの仕組み

アカウントWebhookは次の手順で動作します。

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

複数のエンドポイントが同じイベントを購読している場合、各エンドポイントはそれぞれ個別の配信を受け取ります。ビジネスイベントのEvent IDはすべて同じですが、各配信には固有のDelivery IDがあります。

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

Webhookページを開く

「設定」を開き、「開発者」を展開して「Webhook」を選択します。

ページには主に次の3つの領域があります。

署名シークレット
エンドポイント
選択したエンドポイントの配信履歴

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

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

Maildroppaを設定する前に、サーバー上に受信処理を準備します。受信処理には次の要件があります。

公開HTTPS URLで利用できること。
application/jsonボディを含むPOSTリクエストを受け付けること。
Maildroppaの署名を検証するまで、元のリクエストボディを保持すること。
イベントを安全に受け入れた後にのみ、2xxステータスを返すこと。
Event IDを使用して、重複配信を冪等に処理すること。
リクエスト中に時間のかかる処理を行わず、すばやく応答すること。

信頼性の高い方法は、リクエストを検証し、Event IDとペイロードを永続キューまたはデータベースに保存して、200または204を返し、その後にビジネス処理を行うことです。

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

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

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

ページ上部の署名シークレットパネルには、次のいずれかの状態が表示されます。

未設定 — 署名シークレットがまだ存在しません。
準備完了 — 署名シークレットが設定されています。
読み込み中 — Maildroppaが現在の状態を取得しています。

ステータスが「未設定」の場合は、「シークレットを生成」をクリックします。

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

完全な値が表示されるのは、生成またはローテーションの直後のみです。ページを再読み込みするか離れると、Maildroppaはシークレットが存在することと、最後に更新された日時だけを表示します。保存されたシークレットを再び表示することはありません。

Webhook: 新しい署名シークレット

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

受信処理に現在のシークレットがない場合は、「シークレットをローテーション」をクリックし、新しく表示された値を保存します。

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

新しい配信、スケジュールされた再試行、テスト、再送は、HTTPリクエストの時点で現在のシークレットを使用して署名されます。つまり、ローテーション前に作成された配信でも、その後に試行される際には新しいシークレットで署名される場合があります。

シークレットはパスワードと同じように扱う

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

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

Webhook署名を検証する

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

X-Maildroppa-Event-Id — ビジネスイベントを識別します。
X-Maildroppa-Delivery-Id — 特定の配信を識別します。
X-Maildroppa-Timestamp — Unix秒単位の署名時刻です。
X-Maildroppa-Signature — バージョン付きHMAC署名です。

Maildroppaは次のヘッダーも送信します。

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：エンドポイントを追加する

「エンドポイント」セクションで「エンドポイントを追加」をクリックします。

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

エンドポイントURL
イベント
カスタムヘッダー
有効状態

新しいエンドポイントは有効として開始され、エディターに表示されるすべてのイベントが最初から選択されています。保存する前に選択内容を確認し、受信処理が実際に必要とする通知だけを受け取るようにしてください。

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`

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

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

このイベントを、すべての登録でDouble Opt-inが完了した証拠と解釈しないでください。ペイロード内の購読者ステータスには現在の状態が示されます。

購読者が更新された — `subscriber.updated`

組み込みの購読者情報またはカスタムフィールドの値が変更されたときに送信されます。

ペイロード内の完全な購読者オブジェクトを、現在のMaildroppa上の表現として使用してください。特定のプロパティだけが変更されたと想定しないでください。

タグの付与と削除には独自のイベントタイプがあるため、別々に処理できます。

購読者が購読解除された — `subscriber.unsubscribed`

購読解除操作によって購読者が購読解除済み状態になったときに送信されます。

このイベントを使用して、接続されたシステムで連絡先への送信を抑制します。別のシステムでその連絡先がまだアクティブとして扱われているからといって、自動的に再購読させないでください。

タグが追加された — `subscriber.tag_added`

購読者にタグが割り当てられたときに送信されます。

ペイロードには、今回の変更に関係する購読者とタグが含まれます。

タグが削除された — `subscriber.tag_removed`

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

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

フォームが送信された — `form.submitted`

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

これはフォーム送信のシグナルであり、Double Opt-inが完了した確認ではありません。確認済みの購読を必要とするワークフローでは、購読者の現在のステータスと確認プロセスを引き続き尊重する必要があります。

役割が異なる場合は別々のエンドポイントを使用する

異なるイベントを異なるシステムに送信できます。例：

購読者イベントとタグイベントをCRMに送信する。
購読解除イベントを抑制サービスに送信する。
フォーム送信イベントを分析パイプラインに送信する。

エンドポイントを分けると不要なトラフィックを減らし、障害の診断を容易にできます。各エンドポイントには、独自のイベント選択、URL、カスタムヘッダー、有効状態、テスト、配信履歴があります。

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

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

「ヘッダーを追加」をクリックし、ヘッダー名とヘッダー値を入力します。適切な例：

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は、保存前にカスタムヘッダー値を暗号化します。保存された値が読み取り可能な形式でブラウザに返されることはありません。

後でエンドポイントを編集すると、値フィールドには「保存済みの値を保持」と表示されます。既存のシークレットを変更しない場合は空欄のままにします。置き換える場合は新しい値を入力します。

ヘッダー名を変更する場合は、値をもう一度入力してください。Maildroppaは、元のヘッダー名が変更されない場合にのみ保存されたシークレットを保持します。

ヘッダー行を削除すると、エンドポイントの保存後、そのヘッダーは今後の配信から削除されます。

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

エンドポイントを有効または無効にする

エンドポイントですぐにイベントを受信する準備ができている場合は、「有効」を選択したままにします。

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

無効なエンドポイントは次の状態になります。

新しく発生したイベントを受信しません。
テストWebhookを送信できません。
表示および編集は可能です。
既存の配信履歴は引き続き利用できます。

エンドポイントを有効にしても、無効な間に発生したイベントはバックフィルされません。

URL、イベント選択、ヘッダー、ステータスが正しいことを確認したら、「保存」をクリックします。

エンドポイント一覧を理解する

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

送信先URL。
有効または無効のバッジ。
購読しているイベントタイプ。
カスタムヘッダー数。
エンドポイントが最後に更新された時刻。

利用できる操作は次のとおりです。

オン／オフ — エンドポイントを有効または無効にします。
テスト — 有効なエンドポイントに1件の即時テストリクエストを送信します。
編集 — URL、イベント、ヘッダー、有効状態を変更します。
削除 — 確認後、エンドポイント設定を完全に削除します。

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

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

How Saved Changes Affect Existing Deliveries

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

URLまたはカスタムヘッダーを編集すると、新しく作成される配信に影響します。すでにキューに入っている配信では、元の送信先と保存済みのヘッダー設定が維持されます。

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

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

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

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

Maildroppaは、保存されたエンドポイント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回行われます。テスト配信は本番の再試行スケジュールに入らず、再送もできません。

After the request finishes, the result panel shows:

Test success or Test failed
Event ID
HTTP status, when a response was received
Duration
Delivery ID
Error information, when available
A response excerpt, when the receiver returned a body

The test also appears in Delivery history with a Test badge. Use the “Test” filter to show only test requests.

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へのリダイレクトを返さないでください。Maildroppaで最終URLを設定します。

自動再試行スケジュール

本番配信では、HTTP試行が最大7回行われます。

再試行可能な失敗の後、Maildroppaは次の遅延で次回の試行をスケジュールします。

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

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

スケジュールは個々の失敗した試行から測定されます。配信は非同期で処理され、システム保護の制限も受けるため、実際の配信時刻は少し遅れる場合があります。

可能な限り、表示された「次回の再試行」時刻までに一時的な受信先の問題を修正してください。自動試行が終了した場合は、受信先が正常に戻った後に「再送」を使用します。

配信履歴を理解する

配信履歴は、現在選択されているエンドポイントに属します。どの履歴を表示しているか確認できるよう、セクションヘッダーにエンドポイントURLが表示されます。

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

すべて — 本番配信とテスト配信を表示します。
本番 — 本番イベントの配信のみを表示します。
テスト — 手動テストのみを表示します。

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

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

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

配信の列

各行には次の情報が含まれます。

作成日時 — 配信レコードが作成された時刻。
状態 — 保留中、成功、失敗、Dead。
HTTP — レスポンスステータス、試行回数、所要時間、該当する場合は次回の再試行時刻。
購読者 — イベントが購読者に関連付けられている場合の購読者メールアドレス。
配信 — イベントタイプ、Event ID、Delivery ID。
操作 — 配信が対象の場合の再送。

HTTPリクエストが行われなかった場合、HTTP列には「HTTP試行なし」と表示されます。これは、署名シークレットがない場合や、保存された送信先を安全に使用できなくなった場合など、送信前にMaildroppaがリクエストを拒否したときに発生します。

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

配信状態

保留中は、配信が初回試行またはスケジュールされた再試行を待っていることを意味します。別の試行がスケジュールされている場合は「次回の再試行」が表示されます。

成功は、受信先が2xxレスポンスを返したことを意味します。以後の自動試行は必要ありません。

失敗は、配信が再試行不可能な問題で終了した、HTTP試行前に拒否された、または送信前に停止されたことを意味します。

Deadは、再試行可能な問題についてすべての自動試行が使用され、成功レスポンスを受信できなかったことを意味します。

履歴の保持期間

配信レコードは一定期間保持されます。

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

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

配信を再送する

完了した本番配信をもう一度試行する必要がある場合は、「再送」をクリックします。

再送は、成功、失敗、またはDead状態の本番配信で利用できます。配信が保留中の場合は利用できず、テスト配信も再送できません。

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

新しい保留中の配信を作成します。
新しいDelivery IDを作成します。
元のEvent IDを保持します。
元のイベントタイプとJSONペイロードを保持します。
保存されていた元の送信先URLとカスタムヘッダーのスナップショットを使用します。
新しいリクエストの準備時に現在の署名シークレットを使用します。

再送では、購読者の現在のデータからペイロードを再構築しません。元のイベントスナップショットを再送します。これにより再送を監査でき、過去のイベントの意味が予期せず変わることを防ぎます。

同じ元の配信について、保留中にできる再送は一度に1件だけです。別の再送を要求する前に、その再送が完了するまで待ってください。

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

Maildroppaが成功レスポンスを受信できなかった場合でも、受信先がビジネス処理を完了している可能性があります。そのため、再送によって重複リクエストが発生することがあります。Event IDによる重複排除で、接続されたシステムが処理を繰り返すことを防止できます。

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

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

保存する前に、次の点を確認してください。

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

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

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

設定と履歴を削除せずに連携を一時停止する場合は、オン／オフスイッチを使用します。

エンドポイントをオフにすると、次の状態になります。

新しいイベントはそのエンドポイントにキューされなくなります。
送信対象としてまだ取得されていない保留中の配信は、失敗としてマークされます。
テストが無効になります。
エンドポイントは編集や後での有効化のために引き続き利用できます。

無効化した時点ですでに進行中のリクエストは、完了する場合があります。この違いが連携に重要な場合は、エンドポイントをオフにした後で配信履歴を確認してください。

エンドポイントが無効な間に取りこぼしたイベントは、再びオンにしてもバックフィルされません。

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

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

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

一時停止するために削除を使用しないでください。設定や表示可能な履歴を後で再び必要とする可能性がある場合は、オン／オフスイッチを使用します。

削除する前に、連携の監査で必要なEvent IDまたはDelivery IDを記録してください。

トラブルシューティング

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

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

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

テストが無効になっている

テストは有効なエンドポイントでのみ利用できます。エンドポイントをオンにするか、「有効」を選択して編集し、テスト前に保存してください。

テストにHTTP試行なしと表示される

ステータスが「未設定」の場合は、署名シークレットを生成します。また、送信先ホスト名が公開され、正しく解決されているか確認してください。

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

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

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

また、受信先が独自のAPI認証情報とMaildroppaの署名を混同していないことを確認します。カスタムのAuthorizationヘッダーと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レスポンスを返します。

配信が保留中になっている

HTTP列の「次回の再試行」を確認します。再試行可能な408、429、5xx、または一時的なネットワーク障害の場合、次回のスケジュールされた試行まで配信は保留中のままです。

再試行時刻を過ぎたら「更新」をクリックして最新状態を読み込みます。

配信がDeadになっている

すべての自動試行が使用されました。まず受信処理を修正し、エンドポイントが有効であることを確認してテストWebhookを送信し、その後、本番配信で「再送」を使用します。

本番運用チェックリスト

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

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

これらの対策を講じることで、Webhookページは信頼性の高い連携に必要な2つの側面、つまりアプリケーションへの安全なイベント配信と、Maildroppa内での明確な運用履歴を提供します。

Contents

the email tool that makes email marketing simple