Cách kiểm thử SendGrid Event Webhook trên localhost

Để thử mộtGởiGrid Trình chọn & màutrên máy chủ địa phương, chạy người giám sát của bạn tại địa phương, để lộ cổng của nó với npx portpreview PORTHãy nhập kết quả của điểm kết thúc HTTPS là SendGrid URL Post, và kiểm tra mọi yêu cầu với phím công cộng Signed Event Webhook trước khi xử lý các sự kiện của nó.

Cái gì?GởiGrid Trình chọn & màugửi

Các Event Webhook báo cáo những gì xảy ra sau SendGrid chấp nhận một thông điệp. Những sự kiện có khả năng giải quyết bao gồm processed. delivered. deferred. bounce, và droppedSự kiện đính hôn bao gồm open. clickBáo cáo thư rác và thay đổi đăng ký. Các trường chính xác thay đổi theo kiểu sự kiện, vì vậy đường chủ yếu trên event và coi những cánh đồng tùy chọn là tùy chọn.

Cơ thể yêu cầu là của JSON dãySendGrid có thể đặt vài sự kiện trong cùng một PST. Một người quản lý giả định req.body.event sẽ lặng lẽ bỏ lỡ mẻ đá. Viên chức Event Webhook tham khảo tài liệu hướng dẫn sử dụng tên và trường, bao gồm sg_event_id và sg_message_id.

Dùng sự kiện làm sự kiện, không phải lệnh. Ví dụ, một sự kiện delivered có thể cập nhật trạng thái của thông điệp, trong khi nhấn chuột có thể phụ thêm một kỷ lục đính hôn. Tránh làm cho một người điều khiển nhấp chuột ghi đè lên một trạng thái sau này hung thủ chỉ vì yêu cầu được đưa ra ngoài trật tự.

1. Tạo điểm kết thúc cục cục bộ

Ví dụ này Express cố ý áp dụng một phân tích cơ thể thô chỉ để SendGrid tuyến đường. Xác thực chữ ký phụ thuộc vào các byte chính xác SendGrid đã ký; phân tích và tái tạo JSON có thể thay đổi các byte đó.

import express from 'express';
import { EventWebhook, EventWebhookHeader } from '@sendgrid/eventwebhook';

const app = express();
const verifier = new EventWebhook();
const publicKey = verifier.convertPublicKeyToECDSA(
  process.env.SENDGRID_WEBHOOK_PUBLIC_KEY,
);

app.post(
  '/webhooks/sendgrid',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.get(EventWebhookHeader.SIGNATURE());
    const timestamp = req.get(EventWebhookHeader.TIMESTAMP());

    if (!signature || !timestamp || !verifier.verifySignature(
      publicKey,
      req.body,
      signature,
      timestamp,
    )) {
      return res.status(403).send('invalid signature');
    }

    let events;
    try {
      events = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.status(400).send('invalid JSON');
    }
    if (!Array.isArray(events)) {
      return res.status(400).send('expected an event array');
    }

    await enqueueNewEvents(events);
    return res.sendStatus(204);
  },
);

app.use(express.json());
app.listen(3000);

Cài đặt trợ giúp chính thức bằng npm install @sendgrid/eventwebhookGắn kết toàn cục express.json() sau con đường này, hoặc rõ ràng loại bỏ con đường này. Quy tắc tương tự áp dụng trong Next.js, Fastify, NestJS, chức năng không máy chủ, và các cổng ADI: giữ cơ thể ban đầu như là một chuỗi hoặc ate đệm cho đến khi thẩm tra thành công. Chính thức SendGrid Kho lưu nút có một khớp Đã ký Event Webhook ví dụ.

2. Cung cấp SendGrid một URL HTTPS

Giữ ứng dụng chạy, rồi mở thiết bị cuối thứ hai:

npx portpreview 3000

PortPreview in ra nguồn gốc HTTPS công cộng. Nếu đúng vậy. https://example.portpreview.devURL đầy đủ là:

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

Con đường phải trùng với con đường chính xác. Giữ cho đường hầm hoạt động khi kiểm tra. Một đường hầm dẫn tới giao thông; nó không thay thế máy phục vụ địa phương của bạn, vì vậy sự thất bại của kết nối thường có nghĩa là ứng dụng bị dừng lại, lắng nghe ở cổng khác, hoặc bị ràng buộc theo cách mà đường hầm không thể đến được.

3. Cấu hình Event Webhook trong SendGrid

1. TrongGởiGridMở ra Thiết lập>Thiết lập thư.
2. Dưới thiết lập móc, mở Event Webhook và chọn Tạo ô xem thử mới.
3. Bật nó, thêm địa chỉ URL PortPreview như là URL Post, và chọn chỉ những hành động mà ứng dụng của bạn cần.
4. Dưới tính năng bảo mật, bật Signed Event Webhook.
5. Lưu webok, mở lại thiết lập của nó, sao chép các tạo ra các khóa xác thực công cộng, và lưu trữ nó như SENDGRID_WEBHOOK_PUBLIC_KEY.
6. Dùng Hãy thử sự hợp nhất của bạnSau đó, hãy gửi một thông điệp thật sự để thực hành những biến cố quan trọng.

GởiGridHiện tại hướng dẫn thiết lập ghi chú rằng cuộc kiểm tra gửi các sự kiện ví dụ thay vì dữ liệu từ một thư thật. Lưu trước khi kiểm tra xác thực: cặp chìa khóa được tạo ra khi cấu hình Signed Event Webhook được lưu.

Làm thế nào SendGrid đã ký xác thực web

Trình chọn & màusử dụngECDSA.GởiGridgiữ khóa riêng và hiển thị chìa khóa kiểm tra công cộng tương ứng cho bạn. Mỗi lần giao hàng bao gồm X-Twilio-Email-Event-Webhook-Signature và X-Twilio-Email-Event-Webhook-TimestampTính toán thời gianShip-256hash; chữ ký làCăn cứ64- Đã mã hóa. Người giúp đỡ chính thức quản lý việc chuyển đổi phím công cộng, giải mã chữ ký, hathing, vàECDSAXác thực.

Đây là xác minh đối xứng: giá trị hiển thị là chìa khóa công cộng, không phải bí mật HMAC. Đừng chạy tải về JSON.stringify()(Tiếng cười) Kiểm tra toàn bộ yêu cầu byte trước, rồi phân tích dãy. Xem SendGrid Tài liệu hướng dẫn bảo mật cho thuật toán và đầu đề.

Một chữ ký hợp lệ xác nhận rằng byte đã ký đến từ chìa khóa riêng của SendGrid và không bị thay đổi. Nó không làm cho việc xử lý sự kiện một cách bình đẳng, có quyền hành động tùy tiện, hoặc chứng minh một sự kiện là mới mẻ. Đó là những điều khiển riêng biệt.

Tạo bản phân cách xử lý hàng loạt

GởiGridViệc hồi âm thất bại, và mạng lưới có thể mất phản ứng thành công. Do đó, giao hàng song sinh là bình thường. Dùng mỗi sự kiện sg_event_id là chìa khóa tự hủy chính, với một cơ sở dữ liệu độc đáo. Nếu sản phẩm của bạn kết hợp nhiềuGởiGridTài khoản hay môi trường, không gian tên khoá theo nhà cung cấp và tài khoản hoặc môi trường.

async function enqueueNewEvents(events) {
  for (const event of events) {
    await db.transaction(async (tx) => {
      const inserted = await tx.webhookReceipts.insertIfAbsent({
        provider: 'sendgrid',
        eventId: event.sg_event_id,
        receivedAt: new Date(),
      });
      if (!inserted) return;

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

Tờ hóa đơn được chèn và theo dõi bền vững nên cam kết với nhau. Chỉ có 2xx sau khi mẻ đá là chắc chắnchấp nhậnNếu một sự kiện thất bại sau khi những sự kiện khác phạm tội, một phản ứng không phải là 2xx có thể gây ra toàn bộ yêu cầu trở lại; việc lặp lại cho phép sự cố tiếp theo bỏ qua sự kiện đã được đưa rachấp nhậnvà tiếp tục an toàn. Không dùng bộ nhớ Set trong sản xuất bởi vì khởi động lại xóa nó và nhiều trường hợp không chia sẻ nó. Rộng hơn Cấu hình các thiết lập cache ở đây. Name bao gồm những khuôn mẫu bền vững.

Hiểu hồi quy trước khi chọn mã trạng thái

Theo tài liệu hướng dẫn SendGrid của Event Webhook, phản ứng 2xx đánh dấu thành công PST. Phản ứng không phải là 2xx gây ra sự lặp lại tại khoảng thời gian tăng lên đến 24 giờ sau sự kiện; đây là một cửa sổ quay cho mỗi sự kiện thất bại mới. Hành vi đó có nghĩa là một lỗi chữ ký vĩnh viễn cũng có thể tạo ra nỗ lực lặp đi lặp lại, trong khi trả lại 2x cho một sự kiện bạn không bao giờ lưu trữ mất nó.

• 2x: mẻ hoàn chỉnh đã được xác thực và chắc chắn accepted, hoặc mỗi sự kiện đã được biết.
• 4x: Nhập dạng sai hoặc chưa xác thực. Ghi chép chỉ an toàn chẩn đoán; mong đợi SendGrid hành vi thử lại không phải là 2x.
• 5xx: Một cơ sở dữ liệu, hàng đợi hoặc bị lỗi ứng dụng nên được lấy lại.

Giữ con đường yêu cầu ngắn: xác nhận, xác nhận hình dạng bên ngoài, phân hủy nguyên tử và tiếp tục tiến hành, rồi đáp ứng. Thực hiện cập nhật phân tích thư điện tử, đồng bộ CRM, và thông báo trong công nhân.

Gặp khó khăn khi bắn vào các lưỡi cắm SendGrid cục bộ

Chữ ký luôn không hợp lệ

Nguyên nhân phổ biến nhất là JSON phần mềm trung gian tiêu thụ cơ thể trước khi xác thực. Xác nhận rằng các verifier nhận được gốc BufferBao gồm cả bất cứ đầu mối hay dấu vết nào. Sau đó kiểm tra rằng chìa khóa công cộng thuộc về cấu hình chính xác Event Webhook này và cả hai Twilio đầu trang đến ứng dụng không thay đổi. Khởi động lại quá trình địa phương sau khi thay đổi môi trường.

Comment

Kiểm tra xem các kết nối Mạng đã bật và các hành động mong muốn sẽ được chọn. Mở cần thiết theo dõi mở, và nhấn chuột cần thiết để theo dõi. Cũng hãy nhớ rằng yêu cầu thử nghiệm chứa những ví dụ; sử dụng một thực tế gửi để xác nhận các lĩnh vực và trình tự sản xuất.

Điểm kết thúc trả lại 404 hoặc 502

Đối với 404, so sánh đường dẫn đã cấu hình với /webhooks/sendgridHãy kiểm tra xem ứng dụng cục bộ đang chạy trên cùng cổng được gửi cho PortPreview. Nếu yêu cầu đến nhưng trả lại 500, hãy kiểm tra nhật ký địa phương và tạm thời giảm bớt người điều khiển để xác thực, cộng với việc bắt giữ bền bỉ.

Sự kiện bị lặp lại hoặc không có thứ tự

Đó là một thực tế hệ thống giao hàng, không phải bằng chứng cho thấy đường hầm đã nhân đôi. Phức tạp bởi sg_event_idKhi có thể, hãy thay đổi trạng thái, và lưu trữ thời gian từ thời gian. Sử dụng Name để cô lập vận chuyển, xác thực và thất bại kinh doanh.

Danh sách bảo mật cho việc sử dụng địa phương và sản xuất

• Dùng HTTPS và kiểm tra mọi chữ ký trước khi phân tích hoặc ghi lưu chi tiết sự kiện.
• Giữ chìa khóa kiểm tra công cộng trong cấu hình để nó có thể được cập nhật sạch khi phím kiểu web thay đổi.
• Chấp nhận chỉ, kích cỡ yêu cầu giới hạn, xác nhận giá trị phân tích là một dãy, và chỉ cho phép tên sự kiện bạn xử lý.
• Đừng đặt PII trong SendGrid loại hoặc lập luận độc đáo; SendGrid cảnh báo rõ ràng rằng những trường đó được lưu trữ và không được xem là PII.
• Đừng để lộ một phiên họp quản trị, một giao diện gỡ lỗi, hoặc một lộ trình địa phương không liên quan thông qua cùng nguồn gốc tạm thời.
• Đừng ghi lại địa chỉ, tải, ký hiệu hoặc giá trị môi trường, trừ khi cần thiết và cần thiết.
• Thay thế địa chỉ URL đường hầm tạm thời bằng điểm kết thúc HTTPS ổn định sau khi kiểm tra, và tắt cấu hình nút mạng cũ.

SendGrid cũng có thể sử dụng OAuth 2.0 cho Event Webhook an ninh, một mình hoặc cùng với chữ ký. Nếu việc triển khai của anh cần kiểm soát sự sống, hãy theo hướng dẫn viên chính thức thay vì phát minh ra một cuộc trao đổi. Việc xác minh chữ ký vẫn có giá trị vì nó kết nối thời gian chính xác và tải theo dõi.

Một bài kiểm tra chấp nhận sẵn sàng

1. Gửi yêu cầu kiểm tra có chữ ký và xác nhận phản ứng 2xx
2. Thay đổi một đơn vị hạng sang và xác nhận dữ liệu 403 mà không cần ghi.
3. Chơi lại yêu cầu hợp lệ giống hệt nhau và xác nhận không có việc làm trùng hay hành động kinh doanh.
4. Gửi một đối tượng JSON thay vì một danh sách và xác nhận 400 người bị kiểm soát.
5. Dừng cơ sở dữ liệu một thời gian ngắn, xác nhận một 5xx, phục hồi nó, và xác nhận rằng một thử lại là accepted một lần.
6. Gửi một email thật và xác nhận sự kiện đã chọn và đính hôn theo cùng một đường dẫn.

Một khi các kiểm tra này được thông qua, hãy chuyển điểm kết thúc đến sản xuất mà không thay đổi sự xác minh và lý luận thuần túy. Để có chế độ giải mã sâu hơn, đọc các Hướng dẫn xác thực lựa chọn.