Cách kiểm thử Mailgun webhook trên localhost

Để thửMailgunName npx portpreview PORTcấu hình điểm kết thúc HTTPS cho kiểu sự kiện Mailgun cần thiết, và xác nhận nhãn thời gian, thẻ tín dụng và dấu hiệu HMAC-SHA256 trước khi chấp nhận sự kiện.

Sao?MailgunBáo cáo các móc mũi

Mailgun gửi một bản tóm tắt HTTP hoặc HTTPS bằng một quả bom JSON khi một sự kiện cấu hình xảy ra. Kiểu sự kiện hiện thời bao gồm accepted. delivered. temporary_fail. permanent_fail. opened. clickedkhiếu nại thư rác, và đánh dấu. Theo dõi các sự kiện chỉ xuất hiện khi khả năng theo dõi tương ứng được bật.

Một cơ thể Mailgun Send hiện có một signature đối tượng bên cạnh event-dataDữ liệu sự kiện chứa các trường như event. id. timestampThông điệp, thông tin nhận được, thẻ và chi tiết chuyển phát, tùy theo kiểu sự kiện. Mã chống lại các lĩnh vực được ghi nhận và chấp nhận không có tính chất tùy chọn. Mailgun chính thức Name là cách tốt nhất để kiểm tra hợp đồng.

Đừng nhầm lẫn một Mailgun Send webok với Mailgun Báo động. Cảnh báo sử dụng một phím ký khác và ký toàn bộ cơ thể PST vào một X-Sign Đầu trang. Hướng dẫn này bao gồm Hãy gửi các kết nối: các trường chữ ký trong tải và tài khoản là Webhook Signing Key.

1. Xây dựng điểm cuối Mailgun cục bộ

Không giống như những kế hoạch ký tên vào cơ thể JSON thô, Mailgun Send tính toán bằng cách sử dụng nhãn thời gian và vật thể. Do đó, phân hủy tiêu chuẩn JSON là thích hợp. Những người điều khiển Express xác nhận HMAC, thực hiện kiểm tra lại thời gian, và chắc chắn chấp nhận sự kiện.

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);

Cửa sổ 15 phút là một chính sách ứng dụng, không phải một Mailgun giá trị hạn chế. Mailgun khuyên kiểm tra rằng nhãn thời gian không quá xa thời gian hiện tại nhưng cảnh báo về việc quá hung hăng vì có thể bị trì hoãn. Chọn một cửa sổ phù hợp với yêu cầu xếp hàng và sự cố, theo dõi từ chối hợp pháp, và điều chỉnh nó một cách có chủ đích.

Lưu trữ Webhook Signing Key trong một bộ quản lý bí mật hoặc biến môi trường, không bao giờ trong kiểm soát nguồn. Mailgun Hướng dẫn kết nối định nghĩa tính toán chính xác: phân loại thời gian nhãn và hiệu với không dấu định giới, tính HMAC-SHA256 sử dụng Webhook Signing Key, và so sánh thập lục phân tiêu hóa với signature.

2. Đẩy ra máy cục bộ trên HTTPS

Khi ứng dụng nghe trên cổng 3000, chạy:

npx portpreview 3000

Phụ thêm đường dẫn cục bộ tới nguồn gốc HTTPS công cộng. Ví dụ:

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

Để lại cả ứng dụng và đường hầm chạy trong khi kiểm tra. Mailgun cần một địa chỉ URL có thể truy cập công khai; localhost, địa chỉ LAN tư nhân, và một chứng nhận tự phát triển không thích hợp với đích đến từ xa. PortPreview chấm dứt công chúng HTTPS và chuyển yêu cầu tới cổng cục bộ.

3. Cấu hình Mailgun URL sự kiện

Mailgun hỗ trợ cấu hình mạng lưới cấp độ tài khoản và miền. Điểm cuối của tài khoản có thể nhận sự kiện qua các miền và các tiểu số thừa kế; điểm kết thúc miền chỉ áp dụng cho miền đó. Mỗi kiểu sự kiện được cấu hình riêng lẻ và có thể lên đến ba URL. Hãy chọn phạm vi hẹp nhất khớp với ứng dụng của bạn.

1. Mở khu vực Weboks cho tài khoản đã định hoặc gửi miền.
2. Chọn kiểu sự kiện như delivered hay permanent_fail.
3. Thêm đầy đủNameĐiểm cuối HTTPS.
4. Lặp lại cho mỗi sự kiện gõ hỗ trợ người quản lý của bạn.
5. Gửi một thông điệp hoặc kiểm tra yêu cầu và bản ghi ứng dụng.

Mailgun trùng lặp cùng một địa chỉ URL cho cùng một sự kiện khi nó được cấu hình ở mức độ tài khoản và miền, nhưng các URL khác nhau có thể nhận được một bản sao. Di sản của cha mẹ cũng có thể gây ra nhiều điểm kết thúc khác nhau. Xem lại quan chức quy tắc cấu hình trước khi giao thêm hàng cho họ.

Làm thế nàoMailgunXác thực chữ ký

Hạt signature Đối tượng chứa:

• timestamp: Thời gian Unix trong giây.
• token: một chuỗi 50 ký tự ngẫu nhiên được tạo ra
• signature:: một tiêu hóa thập lục phân HMAC.
• parent-signature: tùy chọn hiện diện cho một sự kiện từ tiểu đếm, cho phép hợp lệ hóa mối quan hệ tài khoản chính mà Mailgun miêu tả.

Cho chữ ký tài khoản thông thường, tính HMAC-SHA256(signingKey, timestamp + token)Không có dấu định giới và event-data JSON không phải là một phần của tính toán này Mailgun Send. So sánh byte được giải mã với một chức năng an toàn thời gian sau khi kiểm tra độ dài bằng nhau. Một đồng bằng === So sánh đơn giản hơn, nhưng so sánh về thời gian an toàn là mặc định sản xuất an toàn hơn.

Một HMAC xác thực chứng minh rằng một bên cầm chìa khóa ký hiệu đã tạo ra chữ ký. Nó không chứng minh rằng giao hàng này đã không được tái diễn. Mailgun đặc biệt đề nghị kẹp thẻ và từ chối yêu cầu sau đó với cùng một dấu hiệu. Kiểm tra thời gian có dấu hiệu giới hạn yêu cầu hợp lệ bị bắt còn có ích bao lâu. Dùng cả hai điều khiển: một biểu tượng duy nhất ép phải xem lại và một cửa sổ thời gian hợp lý cho độ tươi.

Làm rối trí cả giao hàng lẫn hiệu ứng

Giữ hai hạn chế tính độc đáo bền vững: một để ký hiệu và một cho Mailgun event-data.idVật kỷ niệm này được ghi lại một cách giống hệt. ID sự kiện bảo vệ logic kinh doanh nếu sự kiện tương tự xuất hiện trong một hoàn cảnh khác hợp lệ. Không gian tên bởi nhà cung cấp và tài khoản hoặc môi trường.

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,
    });
  });
}

Trở lại các thao tác chèn nếu- trường hợp với chỉ mục duy nhất của cơ sở dữ liệu; một đọc theo sau bởi một chèn là rime-prone dưới giao hàng đồng thời. Hãy ghi lại hồ sơ và hàng đợi công việc nguyên tử. Sau đó, hãy thừa nhận nhanh chóng và để cho một công nhân cập nhật thông điệp, cảnh báo kích hoạt, hoặc đồng bộ hóa CRM. Xem Thử lại và hướng dẫn nhận quyền hạn để thay thế khi hàng đợi và cơ sở dữ liệu kinh doanh không thể chia sẻ giao dịch.

Mailgun Mã đáp ứng và hành vi thử lại

Mailgun tài liệu hướng dẫn cho kết quả quan trọng:

• 200 thành công: Mailgun coi cái móc trang web là thành công và không thử lại.
• 406 không thể chấp nhận: Mailgun coi PST như bị từ chối và không thử lại nó.
• Bất kỳ mã số khác: Đối với weboks khác với thông báo giao hàng, Mailgun retries hơn tám giờ trong 5 phút, 10 phút, 15 phút, 1 giờ, 2 giờ, và 4 giờ.

Ghi chú ngoại lệ: không hứa hẹn rằng mỗi kiểu sự kiện theo lịch thử lại chung. Kiểm tra cái mới nhất Tự động sao lưu tài liệu hướng dẫn Khi giao hàng đảm bảo sẽ ảnh hưởng đến thiết kế của bạn.

Dùng 406 chỉ để yêu cầu bạn cố ý từ chối vĩnh viễn, như chữ ký không hợp lệ hoặc chính sách ở ngoài. Sử dụng 500 hoặc 503 cho cơ sở dữ liệu tạm thời và hàng đợi thất bại để các kiểu mạng móc có thể thử lại. Trả lại chỉ sau khi được chấp nhận bền bỉ. Trả lại 200 trong khi bắt đầu công việc không theo dõi có thể mất sự kiện nếu quá trình này kết thúc.

NameMailgunKết nối mạng cục bộ

Các máy tính HMAC không bao giờ khớp

Xác nhận rằng bạn đang sử dụng Webhook Signing KeyKhông phải chìa khóa API, mật khẩu SIS, hay báo động đang ký. Phân loại thời gian và vật thể không có dấu hiệu giới hạn. Tạo ra một hệ thập lục phân thấp hơn SHA-256 tiêu hóa. Cũng xác nhận rằng khuôn khổ của bạn đã không thay đổi các dấu gạch nối event-data ký hiệu khung tránh lỗi đó.

Người quản lý nhận các hình thức lĩnh vực thay vì hiện tại JSON

Kiểm tra tính năng Mailgun nào và điểm kết thúc tạo ra yêu cầu. Không áp dụng một công cụ nạp lại di sản một cách mù quáng vào một trình gửi kết thúc hiện thời. Loại nội dung đăng nhập, tên trường cấp cao, và chiều dài cơ thể trong phát triển mà không cần đăng nhập nội dung hoặc bí mật, sau đó thực hiện các hợp đồng ghi chép cho tài khoản của bạn và sự tích hợp.

Mailgun Tiếp tục thử lại

Kiểm tra tình trạng thực tế được gửi qua dây. Một ngoại lệ sau khi xác định cơ sở dữ liệu có thể biến phản ứng thành 500, gây ra một nỗ lực khác. Đó là lý do tại sao thẻ căn cước và thẻ tín dụng phải độc đáo và bền vững. Nếu yêu cầu là vĩnh viễn không hợp lệ, hãy trả lại 406; nếu lỗi này là tạm thời, hãy sửa dịch vụ và cho phép việc thử lại có hiệu quả.

Name

Xác nhận địa chỉ URL được gắn vào tài khoản hay miền đúng và kiểu sự kiện đang được tạo ra. A delivered URL sẽ không nhận được opened sự kiện. Kiểm tra rằng quá trình và đường hầm địa phương vẫn còn hoạt động và rằng đường dẫn cấu hình là /webhooks/mailgunĐi theo Hướng dẫn gỡ lỗi trên mạng cục bộ để tách nhà cung cấp từ định tuyến và lỗi ứng dụng.

Danh sách bảo mật

• Kiểm tra HMAC trước khi tin hay ghi nhật ký event-data.
• Giữ phím ký trong một cửa hàng bí mật và xoay nó thông qua một triển khai kiểm soát; không bao giờ phơi bày nó trong mã khách hàng bên.
• Sử dụng sự so sánh về tiêu hóa thời gian, chính sách nhãn thời gian và sự ràng buộc độc nhất vô nhị trên biểu tượng.
• Kiểm tra lại kiểu sự kiện và cần thiết trường trước khi truy vấn. Xử lý địa chỉ người nhận, đối tượng, địa chỉ URL lưu trữ, và người dùng biến là dữ liệu nhạy cảm.
• Chấp nhận chỉ PST, kích thước cơ thể, sử dụng HTTPS, và tỷ lệ thất bại mà không chặn các đệ quy Mailgun hợp lệ.
• Không để lộ các điểm phụ trách địa phương không liên quan hoặc gỡ lỗi thông qua nguồn công cộng tạm thời.
• Khi thử ra kết thúc, hãy gỡ bỏ địa chỉ URL tạm thời và cấu hình điểm kết thúc sản xuất ổn định.

Mailgun cũng cung cấp tài liệu về một chứng nhận khách hàng thay đổi tuỳ chọn trên webhoook yêu cầu khi máy phục vụ nhận của bạn có lệ. Điều đó có thể cung cấp khả năng xác thực cấp vận chuyển, nhưng nó không thay thế việc tải dữ liệu HMAC, điều khiển tua lại và cho phép ứng dụng. Điều khiển lớp theo mô hình đe dọa của bạn.

Kiểm tra khả năng sản xuất

1. Đưa ra một sự cố hợp lệ và xác nhận một sự kiện bền vững cộng với 200 câu trả lời.
2. Thay đổi thẻ tín dụng mà không thay đổi chữ ký và xác nhận một chiếc 406 không ghi sự kiện.
3. Lặp lại chính xác cơ thể hợp lệ và xác nhận không có tác dụng phụ hay công việc thứ hai.
4. Gửi một chữ ký hợp lệ có nhãn thời gian bên ngoài cửa sổ đã cấu hình của bạn và xác minh lại sự từ chối đã định.
5. Buộc lỗi cơ sở dữ liệu tạm thời, xác nhận phản ứng không phải 200/200-non-406, sau đó khôi phục cơ sở dữ liệu và xác nhận một thành công chấp nhận.
6. Sử dụng mỗi kiểu sự kiện Mailgun vì việc tải và thử lại mong đợi khác nhau.

Một khi các bài kiểm tra đã qua, hãy sử dụng cùng một con đường xác định và cách nhân bản trong sản xuất. Đối với một giải thích nhà cung cấp phụ thuộc vào so sánh HMAC và bí mật xử lý, đọc Hướng dẫn xác thực lựa chọn.