Як тестувати Mailgun webhook на localhost

Тестування Mailgun webhooks on Localhost, виставити локальний обробник з npx portpreview PORT, налаштуйте отриману URL-адресу HTTPS для необхідних Mailgun типів подій, і перевірте часову пам'ять завантаження, токен і підпис HMAC-SHA256 перед прийняттям заходу.

Що Mailgun webhooks звіт

Mailgun надсилає HTTP або HTTPS POST з завантаженням JSON при налаштуванні події. Типи заходу: acceptedй deliveredй temporary_failй permanent_failй openedй clickedСкарги спаму та відписки. Відстеження залежних заходів тільки при включенні відповідного відстеження.

Поточний Mailgun Send webhook тіло має signature об'єкт поруч event-dataДані заходу містять поля, такі як eventй idй timestamp, головки повідомлень, інформація одержувача, теги та деталі доставки, залежно від типу події. Код з документованих полів і переносить необов'язкові властивості. Mailgun офіційний приклади корисного навантаження є кращими світильниками для тестування контрактів.

Не плутайте Mailgun Send webhook з Mailgun Вставки. Вставки використовують різні ключі входу і підпишіть весь тіло POST в X-Sign головки. Цей посібник охоплює Відправлення webhooks: поля підпису в перевантаженні та обліковому записі Webhook Signing Key.

1. Створіть локальну Mailgun endpoint

На відміну від схем, які визначаються сирим тілом JSON, Mailgun Send, задокументований розрахунок використовує часовий запас підпису та токен. Стандартний парсинг JSON, тому доречний. Наступним Express кермом є HMAC, виконує релей-вивірку, і, безумовно, приймає захід.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.use(express.json({ limit: '1mb' }));

function verifyMailgunSignature({ timestamp, token, signature }) {
  if (!timestamp || !token || !signature) return false;

  const expected = crypto
    .createHmac('sha256', process.env.MAILGUN_WEBHOOK_SIGNING_KEY)
    .update(String(timestamp) + String(token))
    .digest('hex');

  const expectedBytes = Buffer.from(expected, 'hex');
  const actualBytes = Buffer.from(String(signature), 'hex');
  return expectedBytes.length === actualBytes.length &&
    crypto.timingSafeEqual(expectedBytes, actualBytes);
}

app.post('/webhooks/mailgun', async (req, res) => {
  const signing = req.body?.signature;
  const event = req.body?.['event-data'];

  if (!signing || !event || !verifyMailgunSignature(signing)) {
    return res.status(406).send('invalid webhook');
  }

  const ageSeconds = Math.abs(Date.now() / 1000 - Number(signing.timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > 15 * 60) {
    return res.status(406).send('stale webhook');
  }

  await acceptOnce({
    eventId: event.id,
    replayToken: signing.token,
    payload: event,
  });
  return res.sendStatus(200);
});

app.listen(3000);

15-хвилинний вікно є політикою додатків, а не Mailgun-mandated value. Mailgun рекомендує перевірити, що часовий апарат не занадто далеко від поточного часу, але попереджає, що не перейде агресивно, оскільки доставка може бути затримана. Виберіть вікно, яке відповідає вашим вимогам, контролювати законні відхилення та коригувати його навмисно.

Зберігайте Webhook Signing Key в секретному менеджеру або змінній середовища, ніколи не в управлінні джерелом. Mailgun Налаштування інструкцій вебхокс визначає точний розрахунок: концентрований часовий апарат і токен без сепаратора, компute HMAC-SHA256 за допомогою Webhook Signing Key і порівняння шістнадцяткового перетравлення з signatureй

2. Експедиційний локальнийhost над HTTPS

З додатком, що прослуховує порт 3000, запустіть:

npx portpreview 3000

Додайте місцевий маршрут до публічного HTTPS походження. Наприклад:

https://example.portpreview.dev/webhooks/mailgun

Залишити заявку та тунель, що працює під час тестування. Mailgun вимагає публічно доступного URL; localhost, приватна адреса LAN та сертифікат самовизнаного розвитку не підходять дистанційні напрямки. PortPreview припиняє публічний HTTPS і пересуває запит на локальний порт.

3. Налаштування Mailgun URL-адреси подій

Mailgun підтримує налаштування облікового запису та доменного рівня. Кінцеві кінцеві точки облікового запису можуть отримувати події в доменах і спадкових підрахунках; кінцеві точки домену застосовуються тільки до цього домену. Кожен тип заходу налаштований індивідуально і може мати до трьох URL. Виберіть найбільшу сферу, яка відповідає вашому додатку.

1. Відкрийте площу Webhooks для призначеного облікового запису або відправки домену.
2. Виберіть тип події, такі як delivered або permanent_failй
3. Додати повну PortPreview HTTPS endpoint.
4. Повторіть для кожного типу події, який підтримує ваш обробник.
5. Відправте тест або реальне повідомлення і перевірте локальний запит та журнали додатків.

Mailgun deduplicates the же URL для того ж випадку, коли він налаштований на рівні облікового запису та домену, але різні URL-адреси можуть отримувати копію. Парентно-знижковий спадок також може викликати поставки до декількох різних точок. Ознайомтеся з офіційною правила налаштування перед тим, як приділити кожну додаткову доставку на речення.

Як Mailgun робота по перевірці підписів

Про нас signature об'єкт містить:

• timestamp: Унікс час за секундами.
• token: випадково сформований рядок 50-character.
• signature: шістнадцятковий травень HMAC.
• parent-signature: додатково присутній для заходу з підзвіту, що дозволяє вірувати проти первинних відносин облікового запису, описаних Mailgun.

Для звичайного підпису облікового запису, розрахувати HMAC-SHA256(signingKey, timestamp + token). Не існує сепаратора і event-data JSON не входить до цього документованого Mailgun Send обчислення. Порівняйте декодовані байти з функцією timing-safe після перевірки рівних довжини. Скарга === Порівняти простіше, але порівняння timing-safe є за замовчуванням.

Аудиторія HMAC доводить, що партія, яка проводила ключ підпису. Це не доводить, що ця доставка не була перероблена. Mailgun особливо рекомендує кешування токену і відхиляти наступний запит з тим же токеном. Терміни перевірки часу, як довго захоплений дійсний запит залишається корисним. Використовуйте обидва елементи керування: унікальний токенний обмеження для відтворення та розумний час для свіжості.

Deduplicate обидва поставки і ефекти

Зберігати два міцних концентрацій унікальності: один для токена підпису і один для Mailgun event-data.id. Токен зловить ідентичну підписку на доставку. Ідентифікатор заходу захищає логіку, якщо з’являється той самий захід в іншому дійсному контексті доставки. Статус на сервери

async function acceptOnce({ eventId, replayToken, payload }) {
  await db.transaction(async (tx) => {
    const tokenWasNew = await tx.webhookTokens.insertIfAbsent({
      provider: 'mailgun',
      token: replayToken,
    });
    if (!tokenWasNew) return;

    const eventWasNew = await tx.webhookEvents.insertIfAbsent({
      provider: 'mailgun',
      eventId,
      receivedAt: new Date(),
    });
    if (!eventWasNew) return;

    await tx.jobs.enqueue({
      type: 'process-mailgun-event',
      payload,
    });
  });
}

Задня частина вставок-іф-абсентних операцій з базою унікальних індексів; читати далі вставкою є рас-проне під одночасним постачанням. Прийміть записи dedup і чергуйте роботу атомічно. Тоді визнайте швидко і нехай стан оновлення працівника, запустіть сповіщення або синхронізацію CRM. Дивитися Керівництво по переробці та відеоспостереження для альтернативних випадків, коли черга та бізнес-бази не можуть ділитися угодою.

Mailgun коди відповіді та поведінка птиця

Mailgun ''Посилання webhook документації дає три важливі результати:

• 200 Успіхів: Mailgun лікує webhook POST як успішний і не рятує його.
• 406 Неприпустимо: Mailgun лікує POST як відхилений і не торже його.
• Будь-який інший код: Для webhooks, крім повідомлень про доставку, Mailgun бере на себе вісім годин за 5 хвилин, 10 хвилин, 15 хвилин, 1 годин, 2 годин і 4 годин.

Вартість доставки: не обіцяє, що кожен вид заходу повинен бути загальним графіком птиці. Переглянути останнє автоматична документація коли гарантія доставки впливає на ваш дизайн.

Використовуйте 406 тільки для запиту, яку ви навмисно відхиляєте, наприклад, недійсний підпис або повторення зовнішньої політики. Використовуйте 500 або 503 для перенесення бази даних та черги, щоб мати право типів вебхока можуть переробляти. Повернути 200 тільки після міцного прийняття. Повернувшись до 200, починаючи від небажаної фонової роботи може втратити захід, якщо виходи процесу.

Виправлення несправностей Mailgun webhooks локально

Зроблений HMAC ніколи не відповідає

Підтвердіть, що ви використовуєте Webhook Signing Key, не ключ API, пароль SMTP або ключ сигналізації. Конкатенайте часову пам'ять підпису та токени без глухих. Виготовити нижню клітковину SHA-256 травлення. Також перевірте, що ваш каркас не перейменований на event-data майно; позначення брекету дозволяє уникнути помилки.

ручник отримує форму поля замість поточного JSON

Перевірити, які Mailgun мають функцію та кінцеву версію, створену за запитом. Не застосуйте підручник з завантаження спадщини, сліпо до поточного Надіслати webhook. Введіть номер мобільного, який Ви вказали при укладаннi договору з банком - для ідентифікації.

Mailgun продовжує переробку

Перевірка фактичного стану, відправленого на дріт. Виняток після прийняття бази даних може перетворити відповідь на 500, викликаючи іншу спробу. Саме тому вставки заходу ID і Token повинні бути унікальними і довговічними. Якщо запит остаточно недійсний, повертає 406; якщо відмова передається, зафіксуйте послугу і дайте поведінкові дії для роботи.

Відсутні події

Підтвердіть URL-адресу, прикріплену до коректного облікового запису або домену та до певного типу події. Р delivered URL не буде отримувати opened події. Перевірити, що локальний процес і тунель ще активні, і що налаштований шлях /webhooks/mailgun. Слідувати локальний вебхоок деbugging керівництво до окремої конфігурації провайдера від маршрутизації та помилок додатків.

Контроль безпеки

• Перевірити HMAC перед довірою або залогою event-dataй
• Зберігати ключ входу в секретний магазин і обертати його через контрольоване розгортання; ніколи не виставити його в коді клієнта.
• Використовуйте порівняння timing-safe травлення, часової політики, і міцні унікальні обмеження на токен.
• Визначте тип події та необхідні поля перед зарахуванням. Утилітати адреси одержувача, суб'єкти, URL-адреси зберігання та зміни користувачів, як конфіденційні дані.
• Прийміть тільки POST, розмір тіла капелюшок, використовуйте HTTPS, і безблокування законних Mailgun речення.
• Не піддається необумовленому локальному адміністратору або дебюгові кінцеві точки через тимчасовий громадський походження.
• Під час тестування закінчується, видаліть тимчасову URL-адресу і налаштуйте стабільну кінцеву точку виробництва.

Mailgun також документи додаткового сертифікату клієнтів TLS на запитах webhook при отриманні сервера діє TLS. Це може забезпечити перевірку рівня транспорту, але це не замінює перевантаження HMAC, контроль відтворення та авторизація додатків. Контроль шарів відповідно до моделі загрози.

Тести прийняття продукції

1. Підтвердіть дійсну підписку і підтвердіть один міцний захід плюс відповідь 200.
2. Змінити токен без зміни підпису і підтвердити 406 без запису події.
3. Відтворення точного дійсного тіла і підтвердження не другого завдання або побічного ефекту.
4. Відправте дійсний підпис з таймером поза вашим настроєним вікном і перевірте призначене відхилення.
5. Примусити тимчасову помилку бази даних, підтвердити відповідь не-200/не-406, потім відновити базу даних і перевірити один успішний прийом.
6. Вправа кожен налаштований Mailgun тип події, тому що різні види навантаження і очікування птих.

Після того, як ті тести проходять, використовують однакову перевірку та шлях дедупації у виробництві. Для провайдера-залежного пояснення порівняння HMAC та таємного обслуговування, читайте Керівництво по перевірці підписів Webhookй