Webhook

メールイベントをリアルタイムで受信しましょう。

概要

Webhookを設定すると、メール送信、開封、クリックなどのイベントが発生した際に、指定したURLにHTTP POSTリクエストが送信されます。

イベントタイプ

Event	Description
`email.sent`	メールが送信された時
`email.delivered`	メールが受信者に配信された時
`email.opened`	受信者がメールを開封した時
`email.clicked`	受信者がメール内のリンクをクリックした時
`email.bounced`	メールがバウンスした時
`email.complained`	受信者がスパムとして報告した時
`subscriber.created`	新しい購読者が追加された時
`subscriber.unsubscribed`	購読者が配信停止した時
`campaign.sent`	キャンペーン送信が開始された時
`campaign.completed`	キャンペーン送信が完了した時

ペイロード形式

すべてのWebhookリクエストには、以下の形式のJSONペイロードが含まれます:

{
  "event": "email.opened",
  "timestamp": "2026-01-10T12:00:00+00:00",
  "data": {
    "campaign_id": 123,
    "campaign_uuid": "abc-123...",
    "campaign_name": "January Newsletter",
    "subscriber_id": 456,
    "subscriber_uuid": "def-456...",
    "subscriber_email": "user@example.com",
    "ip_address": "1.2.3.4",
    "user_agent": "Mozilla/5.0...",
    "occurred_at": "2026-01-10T12:00:00+00:00"
  }
}

リクエストヘッダー

Header	Description
`Content-Type`	`application/json`
`X-Webhook-ID`	Webhook UUID
`X-Webhook-Event`	イベントタイプ（例: email.opened）
`X-Webhook-Signature`	HMAC-SHA256署名

署名検証

Webhookリクエストの真正性を確認するため、X-Webhook-Signatureヘッダーを検証してください。署名はWebhookシークレットとリクエスト本文を使用したHMAC-SHA256ハッシュです。

PHP例

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your_webhook_secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    die('Invalid signature');
}

$data = json_decode($payload, true);
// Process the event...

Node.js例

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Express.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, 'your_secret')) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event...
  res.status(200).send('OK');
});

リトライポリシー

• Webhook送信が失敗した場合（2xx以外のレスポンス）、自動的にリトライされません。
• 5回連続失敗するとWebhookは自動的に無効化されます。
• 無効化されたWebhookはダッシュボードから再度有効化できます。
• レスポンス時間は10秒以内である必要があります。

ベストプラクティス

• 常に署名を検証してリクエストの真正性を確認してください。
• Webhook処理はできるだけ早く（5秒以内に）完了してください。
• 長時間の処理はキューに入れ、200 OKを即座に返してください。
• HTTPSエンドポイントを使用してデータを安全に転送してください。