Cấu hình Webhooks

Published: 16 tháng 7, 2026 · Last updated: 21 tháng 7, 2026 · By Marcus Biel

Webhooks cho phép Maildroppa thông báo cho một ứng dụng khác khi có điều gì quan trọng xảy ra trong tài khoản của bạn.

Thay vì liên tục hỏi Maildroppa xem một subscriber đã được tạo, cập nhật, hủy đăng ký hay gán thẻ chưa, ứng dụng của bạn có thể nhận một yêu cầu HTTPS ngay sau khi sự kiện xảy ra.

Trang Webhooks là nơi quản lý tập trung cho hoạt động tích hợp trên toàn tài khoản. Bạn có thể tạo nhiều endpoint, chọn các sự kiện mà mỗi endpoint nhận, thêm header xác thực, kiểm tra kết nối, xem các lần gửi và gửi lại một sự kiện production khi cần.

Webhooks cấp tài khoản hoạt động như thế nào

Một webhook cấp tài khoản hoạt động theo quy trình sau:

1. Một sự kiện xảy ra trong Maildroppa, chẳng hạn như một subscriber được tạo.
2. Maildroppa tìm mọi endpoint đang hoạt động và đã đăng ký sự kiện đó.
3. Maildroppa tạo một lần gửi cho mỗi endpoint phù hợp.
4. Payload JSON được ký bằng Signing secret webhook của tài khoản bạn.
5. Maildroppa gửi yêu cầu POST qua HTTPS đến URL endpoint đã lưu.
6. Endpoint của bạn xác minh chữ ký, lưu trữ hoặc xử lý sự kiện rồi trả về phản hồi HTTP.
7. Maildroppa ghi lại kết quả trong lịch sử gửi và tự động thử lại các lỗi tạm thời.

Nếu nhiều endpoint đăng ký cùng một sự kiện, mỗi endpoint sẽ nhận một lần gửi riêng. Sự kiện nghiệp vụ có cùng Event ID trên tất cả các endpoint, trong khi mỗi lần gửi có Delivery ID riêng.

Webhook cấp tài khoản khác với bước “Send a webhook” bên trong một Automation. Webhook cấp tài khoản lắng nghe các sự kiện tài khoản đã chọn trên toàn Maildroppa. Webhook của Automation chỉ được gửi khi subscriber đến đúng bước đó. Cả hai đều sử dụng Signing secret webhook của tài khoản, vì vậy việc xoay vòng secret sẽ ảnh hưởng đến mọi bộ nhận webhook gửi đi có xác minh chữ ký Maildroppa.

Mở trang Webhooks

Mở “Settings”, mở rộng “Developers” rồi chọn “Webhooks”.

Trang này có ba khu vực chính:

• Signing secret
• Endpoints
• Lịch sử gửi của endpoint được chọn

Khi có nhiều endpoint, hãy chọn một hàng endpoint để hiển thị lịch sử gửi của endpoint đó. Nếu bạn chưa chọn rõ ràng, Maildroppa sẽ hiển thị lịch sử của endpoint đầu tiên trong danh sách.

Trước khi tạo endpoint

Hãy chuẩn bị một bộ nhận trên máy chủ trước khi cấu hình Maildroppa. Bộ nhận cần:

• Có thể truy cập qua URL HTTPS công khai.
• Chấp nhận yêu cầu POST với phần thân application/json.
• Giữ nguyên phần thân yêu cầu thô cho đến khi chữ ký Maildroppa được xác minh.
• Chỉ trả về trạng thái 2xx sau khi sự kiện đã được tiếp nhận an toàn.
• Xử lý các lần gửi lặp lại theo cách idempotent bằng Event ID.
• Phản hồi nhanh thay vì thực hiện công việc chậm trong lúc xử lý yêu cầu.

Một mô hình đáng tin cậy là xác minh yêu cầu, lưu Event ID và payload vào hàng đợi hoặc cơ sở dữ liệu bền vững, trả về 200 hoặc 204, rồi xử lý tác vụ nghiệp vụ sau đó.

Không công khai máy tính phát triển, địa chỉ mạng cục bộ hoặc script không được bảo vệ làm bộ nhận webhook production. Maildroppa chỉ chấp nhận các đích HTTPS công khai và kiểm tra lại đích khi gửi một lần gửi.

Bước 1: Tạo Signing secret

Mọi yêu cầu webhook của Maildroppa đều được ký. Bộ nhận của bạn sử dụng Signing secret để xác minh rằng yêu cầu được tạo bởi Maildroppa và phần thân không bị thay đổi trong quá trình truyền.

Ở đầu trang, bảng Signing secret hiển thị một trong các trạng thái sau:

• Missing — Chưa có Signing secret.
• Ready — Đã cấu hình Signing secret.
• Loading — Maildroppa đang lấy trạng thái hiện tại.

Nhấp “Generate secret” khi trạng thái là Missing.

Maildroppa hiển thị secret mới ngay lập tức. Secret bắt đầu bằng whsec_. Nhấp “Copy” rồi lưu secret trong trình quản lý secret hoặc cấu hình môi trường được bảo vệ mà bộ nhận của bạn sử dụng.

Toàn bộ giá trị chỉ được hiển thị ngay sau khi tạo hoặc xoay vòng. Khi bạn tải lại hoặc rời khỏi trang, Maildroppa chỉ cho biết secret tồn tại và thời điểm cập nhật lần cuối. Maildroppa không hiển thị lại secret đã lưu.

Nếu bạn làm mất secret

Nếu bộ nhận không còn secret hiện tại, hãy nhấp “Rotate secret” và lưu giá trị mới được hiển thị.

Việc xoay vòng thay thế secret trước đó ngay lập tức. Maildroppa không giữ cả hai giá trị trong một khoảng thời gian chuyển tiếp. Hãy cập nhật mọi bộ nhận sử dụng secret tài khoản này trước khi gửi các bài kiểm tra tiếp theo hoặc dựa vào các lần gửi production.

Các lần gửi mới, lần thử lại đã lên lịch, bài kiểm tra và lần gửi lại đều được ký bằng secret hiện tại tại thời điểm yêu cầu HTTP được thực hiện. Điều này có nghĩa là một lần gửi được tạo trước khi xoay vòng vẫn có thể được ký bằng secret mới khi được thử sau đó.

Xem secret như mật khẩu

Không đặt Signing secret trong mã trình duyệt, kho lưu trữ công khai, URL, trang lỗi hoặc log ứng dụng thông thường.

Chỉ bộ nhận phía máy chủ cần secret. Nếu bạn cho rằng secret đã bị lộ, hãy xoay vòng secret và cập nhật ngay tất cả bộ nhận.

Xác minh chữ ký webhook

Mỗi yêu cầu chứa các header Maildroppa sau:

• X-Maildroppa-Event-Id — Xác định sự kiện nghiệp vụ.
• X-Maildroppa-Delivery-Id — Xác định lần gửi cụ thể này.
• X-Maildroppa-Timestamp — Thời điểm ký theo Unix seconds.
• X-Maildroppa-Signature — Chữ ký HMAC có phiên bản.

Maildroppa cũng gửi:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

Chữ ký có định dạng:

v1=<lowercase hexadecimal HMAC>

Maildroppa tạo chữ ký bằng HMAC-SHA256. Nội dung được ký là timestamp, tiếp theo là dấu chấm, rồi đến chính xác phần thân JSON thô của yêu cầu:

<timestamp>.<raw request body>

Sử dụng Signing secret làm khóa HMAC.

Ví dụ Node.js sau đây minh họa bước xác minh cốt lõi. rawBody phải là các byte gốc của yêu cầu, không phải JSON đã được phân tích rồi tuần tự hóa lại.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Sau khi xác minh chữ ký, hãy so sánh timestamp với thời gian trên máy chủ. Từ chối các yêu cầu nằm ngoài khoảng dung sai ngắn do hạ tầng của bạn chọn, chẳng hạn năm phút. Điều này giảm nguy cơ một yêu cầu hợp lệ bị thu thập rồi gửi lại sau đó rất lâu.

Chỉ phân tích và xử lý JSON sau khi cả hai bước kiểm tra đều đạt.

Các nguyên nhân phổ biến gây lỗi chữ ký

Chữ ký thường không hợp lệ vì một trong các lý do sau:

• Bộ nhận sử dụng secret cũ sau khi xoay vòng.
• Middleware đã phân tích hoặc thay đổi JSON trước khi tính chữ ký.
• Bộ nhận chỉ ký phần thân và bỏ qua <timestamp>.
• Timestamp được xử lý như một ngày tháng đã định dạng thay vì dùng chính xác giá trị header.
• Bỏ qua tiền tố v1= khi so sánh.
• HMAC được mã hóa theo cách khác thay vì hexadecimal chữ thường.

Hãy ghi log Event ID và Delivery ID khi xác minh thất bại, nhưng tuyệt đối không ghi log Signing secret hoặc các giá trị custom header nhạy cảm.

Bước 2: Thêm endpoint

Nhấp “Add endpoint” trong phần Endpoints.

Trình chỉnh sửa gồm bốn phần:

• Endpoint URL
• Events
• Custom headers
• Active status

Endpoint mới bắt đầu ở trạng thái Active và ban đầu tất cả sự kiện hiển thị trong trình chỉnh sửa đều được chọn. Hãy xem lại lựa chọn trước khi lưu để bộ nhận chỉ nhận những thông báo thực sự cần thiết.

Cấu hình Endpoint URL

Nhập URL công khai đầy đủ sẽ nhận yêu cầu Maildroppa, ví dụ:

https://integrations.example.com/webhooks/maildroppa

URL phải đáp ứng các yêu cầu sau:

• Phải sử dụng https://.
• Phải chứa hostname công khai hợp lệ.
• Có thể dài tối đa 2.048 ký tự.
• Không được chứa biến mẫu với { hoặc }.
• Không được chứa username hoặc password trước hostname.
• Không được chứa fragment URL bắt đầu bằng #.
• Phải sử dụng cổng HTTPS tiêu chuẩn 443.
• Không được sử dụng localhost, địa chỉ IP thô hoặc hostname phân giải thành mạng riêng tư hay mạng dành riêng bị chặn.

Có hỗ trợ tham số truy vấn, nhưng không đặt API key hoặc secret khác trong URL. URL hiển thị trong danh sách endpoint và dữ liệu gửi. Thay vào đó, hãy sử dụng Custom header cho thông tin xác thực.

Maildroppa không theo redirect. Hãy lưu đích HTTPS cuối cùng thay vì URL trả về 301, 302, 307 hoặc 308.

Hostname đích được phân giải lại trước khi gửi. Hostname sau đó phân giải thành địa chỉ riêng tư hoặc bị chặn sẽ bị từ chối ngay cả khi hợp lệ lúc endpoint được lưu.

Chọn sự kiện

Chọn ít nhất một sự kiện. Endpoint chỉ nhận những loại sự kiện được chọn trong trình chỉnh sửa.

Trang cung cấp các lựa chọn sự kiện sau:

Subscriber Created — subscriber.created

Được gửi khi một subscriber được tạo trong tài khoản Maildroppa.

Sử dụng sự kiện này để tạo contact tương ứng trong CRM, nền tảng dữ liệu khách hàng, cơ sở dữ liệu nội bộ hoặc hệ thống khác có khả năng quản lý quyền.

Không diễn giải sự kiện này là bằng chứng rằng mọi lượt đăng ký đã hoàn tất Double Opt-in. Trạng thái subscriber trong payload mô tả trạng thái hiện tại.

Subscriber Updated — subscriber.updated

Được gửi khi thông tin subscriber tích hợp sẵn hoặc giá trị custom field thay đổi.

Sử dụng đối tượng subscriber đầy đủ trong payload làm biểu diễn hiện tại của Maildroppa. Tránh giả định rằng chỉ một thuộc tính cụ thể đã thay đổi.

Việc gán và xóa thẻ có loại sự kiện riêng để có thể xử lý độc lập.

Subscriber Unsubscribed — subscriber.unsubscribed

Được gửi khi subscriber chuyển sang trạng thái unsubscribed thông qua hành động hủy đăng ký.

Sử dụng sự kiện này để loại contact khỏi các hệ thống được kết nối. Không tự động đăng ký lại người đó chỉ vì một hệ thống khác vẫn đánh dấu contact là đang hoạt động.

Tag Added — subscriber.tag_added

Được gửi khi một thẻ được gán cho subscriber.

Payload chứa subscriber và thẻ liên quan đến thay đổi cụ thể này.

Tag Removed — subscriber.tag_removed

Được gửi khi một thẻ bị xóa khỏi subscriber.

Payload chứa subscriber đã cập nhật và thẻ đã xóa. Thẻ đã xóa được cung cấp riêng ngay cả khi không còn xuất hiện trong mảng tags hiện tại của subscriber.

Form Submitted — form.submitted

Được gửi khi khách truy cập gửi biểu mẫu đăng ký Maildroppa.

Hãy xem đây là tín hiệu gửi biểu mẫu, không phải xác nhận Double Opt-in đã hoàn tất. Mọi quy trình yêu cầu đăng ký đã xác nhận vẫn phải tôn trọng trạng thái hiện tại của subscriber và quy trình xác nhận.

Sử dụng endpoint riêng khi trách nhiệm khác nhau

Bạn có thể gửi các sự kiện khác nhau đến các hệ thống khác nhau. Ví dụ:

• Gửi sự kiện subscriber và tag đến CRM.
• Gửi sự kiện hủy đăng ký đến dịch vụ suppression.
• Gửi sự kiện gửi biểu mẫu đến pipeline phân tích.

Endpoint riêng giúp giảm lưu lượng không cần thiết và giúp chẩn đoán lỗi dễ hơn. Mỗi endpoint có lựa chọn sự kiện, URL, custom header, trạng thái hoạt động, bài kiểm tra và lịch sử gửi riêng.

Thêm Custom headers

Custom header là tùy chọn. Sử dụng chúng khi bộ nhận yêu cầu API key, bearer token, mã định danh tenant hoặc một header cố định khác.

Nhấp “Add header”, sau đó nhập Header name và Header value. Ví dụ phù hợp gồm:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Bạn có thể thêm tối đa 20 custom header.

Tên header:

• Là bắt buộc.
• Có thể dài tối đa 128 ký tự.
• Phải sử dụng các ký tự tên header HTTP hợp lệ.
• Phải là duy nhất, không phân biệt chữ hoa chữ thường.

Giá trị header:

• Là bắt buộc.
• Có thể dài tối đa 2.000 ký tự.
• Không được chứa ngắt dòng.

Các tên sau được dành riêng và không thể thay thế bằng custom header:

• Content-Type
• Content-Length
• Host
• User-Agent
• Bất kỳ tên nào bắt đầu bằng X-Maildroppa-

Điều này ngăn giá trị tùy chỉnh thay thế các header gửi và chữ ký của Maildroppa.

Cách lưu trữ secret trong header

Maildroppa mã hóa giá trị custom header trước khi lưu. Các giá trị đã lưu không được trả về trình duyệt ở dạng có thể đọc.

Khi chỉnh sửa endpoint sau đó, trường giá trị hiển thị “Stored value kept”. Để trống nếu secret hiện tại cần được giữ nguyên. Nhập giá trị mới để thay thế.

Nếu bạn thay đổi tên header, hãy nhập lại giá trị. Maildroppa chỉ giữ secret đã lưu khi tên header gốc không thay đổi.

Xóa một hàng header sẽ xóa header đó khỏi các lần gửi tiếp theo sau khi endpoint được lưu.

Giá trị custom header được xem là dữ liệu nhạy cảm trong thông tin yêu cầu đã lưu. Chúng được che đi thay vì hiển thị trong lịch sử gửi.

Đặt endpoint ở trạng thái Active hoặc Inactive

Giữ “Active” được chọn khi endpoint đã sẵn sàng nhận sự kiện ngay lập tức.

Bỏ chọn khi bạn muốn lưu cấu hình mà chưa bắt đầu gửi. Bạn có thể kích hoạt endpoint sau từ danh sách endpoint.

Endpoint inactive:

• Không nhận các sự kiện mới phát sinh.
• Không thể gửi Test webhook.
• Vẫn hiển thị và có thể chỉnh sửa.
• Vẫn giữ lịch sử gửi hiện có để truy cập.

Kích hoạt endpoint không tự động bổ sung các sự kiện đã xảy ra trong thời gian endpoint inactive.

Nhấp “Save” khi URL, lựa chọn sự kiện, header và trạng thái đều chính xác.

Tìm hiểu danh sách endpoint

Mỗi hàng endpoint hiển thị:

• URL đích.
• Nhãn Active hoặc Inactive.
• Các loại sự kiện đã đăng ký.
• Số lượng custom header.
• Thời điểm endpoint được cập nhật lần cuối.

Các thao tác khả dụng:

• On/Off — Kích hoạt hoặc vô hiệu hóa endpoint.
• Test — Gửi một yêu cầu kiểm tra tức thời đến endpoint đang hoạt động.
• Edit — Thay đổi URL, sự kiện, header hoặc trạng thái hoạt động.
• Delete — Xóa vĩnh viễn cấu hình endpoint sau khi xác nhận.

Chọn phần chính của một hàng để mở lịch sử gửi của endpoint đó bên dưới danh sách.

Các thay đổi đã lưu ảnh hưởng đến lần gửi hiện có như thế nào

Một sự kiện tài khoản tạo ra một lần gửi cùng với bản chụp URL endpoint, payload và custom header tại thời điểm đó.

Việc chỉnh sửa URL hoặc custom header ảnh hưởng đến các lần gửi được tạo mới. Lần gửi đã được xếp hàng giữ nguyên đích và cấu hình header ban đầu.

Việc thay đổi các sự kiện đã chọn cũng chỉ ảnh hưởng đến những sự kiện xảy ra sau đó. Maildroppa không tạo các lần gửi hồi tố cho loại sự kiện chưa được chọn khi sự kiện xảy ra.

Signing secret khác với các cấu hình trên: secret được đọc khi yêu cầu HTTP được chuẩn bị. Vì vậy, một lần gửi đang chờ hoặc lần gửi lại có thể sử dụng Signing secret mới được xoay vòng, ngay cả khi payload và bản chụp endpoint được tạo trước đó.

Kiểm tra endpoint

Nhấp “Test” trên endpoint đang hoạt động sau khi bộ nhận và Signing secret đã sẵn sàng.

Maildroppa ngay lập tức gửi một yêu cầu đã ký bằng URL endpoint đã lưu và custom header đã lưu. Các thay đổi chưa lưu trong trình chỉnh sửa đang mở không được đưa vào bài kiểm tra.

Payload kiểm tra sử dụng loại sự kiện webhook.test và đặt livemode thành false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

ID và timestamp được tạo sẽ khác nhau trong mỗi bài kiểm tra thực tế.

Một bài kiểm tra thực hiện chính xác một lần thử HTTP. Lần gửi kiểm tra không được đưa vào lịch thử lại production và không thể gửi lại.

Sau khi yêu cầu hoàn tất, bảng kết quả hiển thị:

• Test success hoặc Test failed
• Event ID
• Trạng thái HTTP khi nhận được phản hồi
• Thời lượng
• Delivery ID
• Thông tin lỗi khi có
• Trích đoạn phản hồi khi bộ nhận trả về phần thân

Bài kiểm tra cũng xuất hiện trong lịch sử gửi với nhãn Test. Sử dụng bộ lọc “Test” để chỉ hiển thị các yêu cầu kiểm tra.

Tìm hiểu payload production

Các sự kiện tài khoản production sử dụng một phong bì JSON chung:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Các thuộc tính cấp cao nhất có ý nghĩa như sau:

• id — Event ID. Khớp với X-Maildroppa-Event-Id.
• type — Khóa sự kiện được chọn trong trình chỉnh sửa endpoint.
• schema_version — Phiên bản schema của payload. Sử dụng khi quyết định cách phân tích sự kiện.
• created_at — Thời điểm payload sự kiện được tạo, theo UTC.
• livemode — true cho sự kiện production và false cho sự kiện kiểm tra.
• data — Nội dung riêng của sự kiện.

Định tuyến sự kiện theo giá trị type chính xác. Bỏ qua các thuộc tính bổ sung mà tích hợp của bạn không cần để việc bổ sung payload tương thích không làm hỏng bộ nhận.

Payload sự kiện subscriber

Các sự kiện subscriber chứa biểu diễn subscriber hiện tại bên trong data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields và tags là các mảng. Chúng có thể rỗng. Một thuộc tính subscriber cũng có thể là null khi không có giá trị, vì vậy bộ nhận nên tuân theo schema payload thay vì giả định mọi giá trị hồ sơ tùy chọn đều tồn tại.

Payload sự kiện tag

Sự kiện tag chứa cả subscriber và tag gây ra sự kiện:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Đối với subscriber.tag_removed, data.tag vẫn xác định tag đã bị xóa ngay cả khi mảng tags hiện tại của subscriber không còn chứa tag đó.

Event ID, Delivery ID và tính idempotent

Event ID và Delivery ID có mục đích khác nhau.

Event ID

Event ID xác định sự kiện nghiệp vụ. Nó xuất hiện trong:

• Thuộc tính id cấp cao nhất của payload.
• Header yêu cầu X-Maildroppa-Event-Id.
• Lịch sử gửi.

Cùng một sự kiện có thể được gửi đến nhiều endpoint đã đăng ký. Các lần gửi đó dùng chung Event ID.

Các lần thử lại và gửi lại thủ công cũng giữ nguyên Event ID ban đầu. Hãy lưu Event ID đã xử lý và đảm bảo hành động nghiệp vụ có tính idempotent để một yêu cầu lặp lại không tạo contact trùng, lặp lại hành động không thể đảo ngược hoặc áp dụng cùng một thay đổi hai lần.

Delivery ID

Delivery ID xác định một bản ghi gửi. Nó xuất hiện trong:

• Header yêu cầu X-Maildroppa-Delivery-Id.
• Lịch sử gửi.

Mỗi lần gửi đến endpoint có Delivery ID riêng. Một lần gửi lại thủ công tạo Delivery ID mới nhưng giữ nguyên Event ID ban đầu.

Sử dụng Delivery ID để theo dõi kỹ thuật và hỗ trợ. Sử dụng Event ID để loại trùng ở cấp nghiệp vụ.

Trả về phản hồi HTTP chính xác

Maildroppa phân loại phản hồi như sau:

• Mọi phản hồi 2xx đều đánh dấu lần gửi thành công.
• Phản hồi 408 Request Timeout, 429 Too Many Requests và 5xx là lỗi tạm thời và có thể được thử lại.
• Các lỗi mạng có khả năng là tạm thời sẽ được thử lại.
• Redirect và các phản hồi 3xx khác không được theo dõi và được xem là lỗi kết thúc.
• Các phản hồi 4xx khác được xem là lỗi kết thúc và không được thử lại.

Chỉ trả về 200, 202 hoặc 204 khi sự kiện đã được tiếp nhận an toàn. Nếu xử lý mất thời gian, hãy lưu sự kiện trước rồi trả về phản hồi thành công trước khi thực hiện phần việc chậm hơn một cách bất đồng bộ.

Không trả về redirect đến URL webhook khác. Hãy cấu hình URL cuối cùng trong Maildroppa.

Lịch tự động thử lại

Các lần gửi production có thể thực hiện tối đa bảy lần thử HTTP.

Sau một lỗi có thể thử lại, Maildroppa lên lịch cho lần thử tiếp theo với các khoảng trễ sau:

1. Sau lần thử 1: 1 phút
2. Sau lần thử 2: 5 phút
3. Sau lần thử 3: 30 phút
4. Sau lần thử 4: 2 giờ
5. Sau lần thử 5: 12 giờ
6. Sau lần thử 6: 24 giờ

Nếu lần thử 7 vẫn nhận lỗi có thể thử lại, lần gửi chuyển thành Dead và không lên lịch thêm lần thử tự động nào.

Lịch được tính từ từng lần thất bại riêng lẻ. Thời điểm gửi thực tế có thể muộn hơn một chút vì các lần gửi được xử lý bất đồng bộ và cũng chịu giới hạn bảo vệ hệ thống.

Hãy khắc phục sự cố tạm thời của bộ nhận trước thời điểm “Next retry” được hiển thị nếu có thể. Nếu các lần thử tự động đã kết thúc, hãy dùng Replay sau khi bộ nhận hoạt động bình thường trở lại.

Tìm hiểu lịch sử gửi

Lịch sử gửi thuộc về endpoint hiện được chọn. URL endpoint xuất hiện trong tiêu đề phần để bạn xác nhận mình đang xem lịch sử nào.

Sử dụng các bộ lọc sau:

• All — Hiển thị các lần gửi production và kiểm tra.
• Production — Chỉ hiển thị các lần gửi sự kiện live.
• Test — Chỉ hiển thị các bài kiểm tra thủ công.

Nhấp “Refresh” để lấy trạng thái mới nhất. Không cần để trang lịch sử mở trong khi Maildroppa gửi hoặc thử lại một lần gửi.

Trang hiển thị 50 lần gửi phù hợp mới nhất cho bộ lọc đã chọn.

Các cột trong lịch sử gửi

Mỗi hàng gồm:

• Created — Thời điểm bản ghi gửi được tạo.
• State — Pending, Success, Failed hoặc Dead.
• HTTP — Trạng thái phản hồi, số lần thử, thời lượng và thời điểm thử lại tiếp theo nếu có.
• Subscriber — Email subscriber khi sự kiện liên kết với subscriber.
• Delivery — Loại sự kiện, Event ID và Delivery ID.
• Actions — Replay khi lần gửi đủ điều kiện.

Nếu chưa thực hiện yêu cầu HTTP nào, cột HTTP hiển thị “No HTTP attempt”. Điều này có thể xảy ra khi Maildroppa từ chối yêu cầu trước khi gửi, chẳng hạn Signing secret bị thiếu hoặc đích đã lưu không còn được sử dụng an toàn.

Khi có, hàng cũng hiển thị Error và Response excerpt do bộ nhận trả về. Không trả secret hoặc dữ liệu cá nhân nhạy cảm trong phần thân phản hồi webhook vì một phần phản hồi có thể xuất hiện trong log gửi của tài khoản.

Trạng thái gửi

Pending nghĩa là lần gửi đang chờ lần thử đầu tiên hoặc lần thử lại đã lên lịch. “Next retry” xuất hiện khi một lần thử khác đã được lên lịch.

Success nghĩa là bộ nhận trả về phản hồi 2xx. Không cần thêm lần thử tự động nào.

Failed nghĩa là lần gửi kết thúc với sự cố không thể thử lại, bị từ chối trước khi thực hiện HTTP hoặc bị dừng trước khi có thể gửi.

Dead nghĩa là tất cả lần thử tự động cho sự cố có thể thử lại đã được sử dụng mà không nhận được phản hồi thành công.

Thời gian lưu giữ lịch sử

Bản ghi gửi được lưu giữ trong thời gian giới hạn:

• Lần gửi production thành công: 30 ngày
• Lần gửi production thất bại: 90 ngày
• Lần gửi production Dead: 90 ngày
• Lần gửi kiểm tra: 30 ngày

Hãy duy trì log tích hợp riêng khi cần lịch sử kiểm toán dài hơn. Lưu Event ID và Delivery ID, nhưng tránh lưu secret nếu không cần thiết.

Gửi lại một lần gửi

Nhấp “Replay” khi một lần gửi production đã hoàn tất cần được thử lại.

Replay khả dụng cho các lần gửi production ở trạng thái Success, Failed hoặc Dead. Không khả dụng khi lần gửi đang Pending và các lần gửi kiểm tra không thể được replay.

Một lần replay:

• Tạo một lần gửi Pending mới.
• Tạo Delivery ID mới.
• Giữ nguyên Event ID ban đầu.
• Giữ nguyên loại sự kiện và payload JSON ban đầu.
• Sử dụng URL đích và bản chụp custom header đã lưu ban đầu.
• Sử dụng Signing secret hiện tại khi yêu cầu mới được chuẩn bị.

Replay không tạo lại payload từ dữ liệu hiện tại của subscriber. Nó gửi lại bản chụp sự kiện ban đầu. Điều này giúp replay có thể kiểm toán và ngăn một sự kiện lịch sử âm thầm thay đổi ý nghĩa.

Mỗi lần gửi nguồn chỉ có thể có một lần replay Pending. Hãy chờ lần replay đó hoàn tất trước khi yêu cầu lần khác.

Đảm bảo endpoint ở trạng thái Active trước khi replay. Nếu endpoint inactive, lần replay đã xếp hàng không thể được gửi thành công.

Vì bộ nhận có thể đã hoàn tất hành động nghiệp vụ ngay cả khi Maildroppa không nhận được phản hồi thành công, replay có thể tạo ra yêu cầu trùng. Việc loại trùng theo Event ID bảo vệ hệ thống được kết nối khỏi việc lặp lại hành động.

Chỉnh sửa endpoint

Nhấp “Edit” để thay đổi URL, lựa chọn sự kiện, custom header hoặc trạng thái hoạt động.

Trước khi lưu:

1. Xác nhận URL mới đã sẵn sàng hoạt động.
2. Để trống các giá trị header đã lưu nếu chúng cần được giữ nguyên.
3. Nhập giá trị mới cho mọi header đã đổi tên.
4. Xem lại lựa chọn sự kiện để không vô tình xóa các thông báo cần thiết.
5. Lưu và gửi một Test webhook mới.

Hãy nhớ rằng các lần gửi đã xếp hàng giữ nguyên URL và bản chụp custom header hiện có. Hãy kiểm tra cấu hình mới cho các lần gửi trong tương lai thay vì giả định rằng nó thay đổi một yêu cầu đã xếp hàng trước đó.

Vô hiệu hóa endpoint

Sử dụng công tắc On/Off khi muốn tạm dừng một hoạt động tích hợp mà không xóa cấu hình và lịch sử.

Khi endpoint được chuyển sang Off:

• Các sự kiện mới không còn được xếp hàng cho endpoint.
• Các lần gửi Pending chưa được nhận để gửi sẽ được đánh dấu Failed.
• Test bị vô hiệu hóa.
• Endpoint vẫn có thể chỉnh sửa và kích hoạt lại sau này.

Một yêu cầu đang được xử lý tại thời điểm vô hiệu hóa vẫn có thể hoàn tất. Hãy kiểm tra lịch sử gửi sau khi chuyển endpoint sang Off nếu sự khác biệt này quan trọng với hoạt động tích hợp của bạn.

Các sự kiện bị bỏ lỡ khi endpoint inactive không được bổ sung khi bạn bật lại.

Xóa endpoint

Nhấp “Delete” và xác nhận cảnh báo khi endpoint không còn cần tồn tại.

Việc xóa loại endpoint khỏi trang, dừng các lần gửi sự kiện trong tương lai và đánh dấu Failed các lần gửi Pending chưa được nhận để gửi.

Delete không phải cách tạm dừng. Hãy sử dụng công tắc On/Off khi bạn có thể cần lại cấu hình hoặc lịch sử hiển thị.

Trước khi xóa, hãy ghi lại Event ID hoặc Delivery ID vẫn cần cho việc kiểm toán tích hợp.

Khắc phục sự cố

Không thể lưu endpoint

Kiểm tra rằng:

• URL bắt đầu bằng https://.
• URL sử dụng hostname công khai và cổng 443.
• URL không chứa biến, thông tin đăng nhập hoặc fragment.
• Đã chọn ít nhất một sự kiện.
• Mỗi Custom header có tên duy nhất và có giá trị.
• Không sử dụng header Maildroppa và HTTP dành riêng làm tên tùy chỉnh.

Test bị vô hiệu hóa

Test chỉ khả dụng với endpoint Active. Bật endpoint hoặc chỉnh sửa endpoint rồi chọn “Active”, sau đó lưu trước khi kiểm tra.

Test không có HTTP attempt

Tạo Signing secret nếu trạng thái là Missing. Đồng thời kiểm tra hostname đích có công khai và vẫn phân giải chính xác hay không.

Yêu cầu có thể bị từ chối trước khi gửi nếu secret, URL, custom header hoặc kiểm tra an toàn đích không hợp lệ.

Bộ nhận trả về 401 hoặc 403

Kiểm tra tên Custom header và thông tin xác thực đã lưu. Chỉnh sửa endpoint và nhập lại giá trị nếu giá trị đã thay đổi.

Đồng thời xác minh rằng bộ nhận không nhầm thông tin xác thực API của chính nó với chữ ký Maildroppa. Custom authorization header và X-Maildroppa-Signature phục vụ các mục đích khác nhau và có thể được kiểm tra độc lập.

Bộ nhận trả về redirect

Maildroppa không theo redirect. Thay URL endpoint bằng URL HTTPS công khai cuối cùng rồi kiểm tra lại.

Chữ ký không khớp

Xác nhận bộ nhận:

• Sử dụng Signing secret hiện tại.
• Sử dụng chính xác giá trị X-Maildroppa-Timestamp.
• Ký <timestamp>.<raw request body>.
• Sử dụng HMAC-SHA256 và kết quả hexadecimal chữ thường.
• So sánh toàn bộ giá trị, bao gồm v1=.
• Thực hiện so sánh trước khi việc phân tích JSON làm thay đổi phần thân.

Cùng một sự kiện đến nhiều lần

Điều này có thể xảy ra sau gián đoạn mạng, lần thử lại hoặc replay thủ công. Hệ thống gửi webhook thường cung cấp giao nhận ít nhất một lần thay vì chính xác một lần.

Sử dụng Event ID làm khóa idempotency. Trả về phản hồi 2xx khi nhận lại Event ID đã được xử lý và không cần hành động bổ sung.

Một lần gửi đang Pending

Xem “Next retry” trong cột HTTP. Lỗi 408, 429, 5xx có thể thử lại hoặc lỗi mạng tạm thời sẽ giữ lần gửi ở trạng thái Pending cho đến lần thử đã lên lịch tiếp theo.

Nhấp “Refresh” sau thời điểm thử lại để tải trạng thái mới nhất.

Một lần gửi ở trạng thái Dead

Tất cả lần thử tự động đã được sử dụng. Trước tiên hãy khắc phục bộ nhận, đảm bảo endpoint Active, gửi Test webhook rồi dùng Replay trên lần gửi production.

Danh sách kiểm tra production khuyến nghị

Trước khi dựa vào endpoint trong production, hãy xác nhận tất cả điều sau:

1. Bộ nhận sử dụng URL HTTPS công khai ổn định với chứng chỉ hợp lệ.
2. Signing secret được lưu bên ngoài mã nguồn.
3. Chữ ký được kiểm tra trên phần thân thô chưa bị thay đổi.
4. Timestamp cũ bị từ chối theo khoảng dung sai đã được ghi nhận.
5. Bộ nhận lưu và loại trùng Event ID.
6. Bộ nhận ghi log Event ID và Delivery ID để theo dõi.
7. Việc xử lý chậm diễn ra sau khi sự kiện đã được tiếp nhận bền vững.
8. Chỉ trả về phản hồi 2xx cho các sự kiện đã được tiếp nhận.
9. Thông tin xác thực tùy chỉnh được lưu trong header thay vì URL.
10. Chỉ chọn các loại sự kiện cần thiết.
11. Test webhook thành công và xuất hiện chính xác trong lịch sử gửi.
12. Hệ thống giám sát cảnh báo khi các lần gửi production bắt đầu trả về lỗi.

Với các biện pháp bảo vệ này, trang Webhooks cung cấp cả hai mặt của một hoạt động tích hợp đáng tin cậy: gửi sự kiện an toàn đến ứng dụng của bạn và lịch sử vận hành rõ ràng bên trong Maildroppa.