웹훅 - MailPass

웹훅

이메일 이벤트를 실시간으로 받아보세요.

개요

웹훅을 설정하면 이메일 발송, 열람, 클릭 등의 이벤트가 발생할 때 지정한 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`	캠페인 발송이 완료되었을 때

페이로드 형식

모든 웹훅 요청은 다음 형식의 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`	웹훅 UUID
`X-Webhook-Event`	이벤트 유형 (예: email.opened)
`X-Webhook-Signature`	HMAC-SHA256 서명

서명 검증

웹훅 요청의 진위를 확인하기 위해 X-Webhook-Signature 헤더를 검증하세요. 서명은 웹훅 시크릿과 요청 본문을 사용한 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');
});

재시도 정책

• 웹훅 전송이 실패하면 (2xx 외의 응답) 자동으로 재시도하지 않습니다.
• 5회 연속 실패 시 웹훅이 자동으로 비활성화됩니다.
• 비활성화된 웹훅은 대시보드에서 다시 활성화할 수 있습니다.
• 응답 시간은 10초 이내여야 합니다.

모범 사례

• 항상 서명을 검증하여 요청의 진위를 확인하세요.
• 웹훅 처리는 가능한 빠르게 (5초 이내) 완료하세요.
• 긴 작업은 큐에 넣고 200 OK를 즉시 반환하세요.
• HTTPS 엔드포인트를 사용하여 데이터를 안전하게 전송하세요.

웹훅

개요