Các endpoint
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` và `listDeliveries`.
Tất cả phương thức
const endpoint = await openemail.webhooks.create({ url: 'https://acme.com/hooks/mail', eventTypes: ['email.sent', 'email.bounced'], description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.webhooks.delete(endpoint.id)create là lần DUY NHẤT mã bí mật được trả về, ngoài rotateSecret. Thao tác đọc không bao giờ trả lại nó, vì vậy hãy lưu nó trước khi làm bất cứ việc gì khác. Bỏ qua eventTypes để nhận mọi sự kiện, kể cả các sự kiện được thêm sau này.
rotateSecret không có khoảng thời gian chồng lấn. Mã bí mật cũ ngừng hoạt động ngay lập tức, vì vậy hãy chuẩn bị sẵn việc triển khai mã mới trước khi xoay vòng. Nó không bao giờ được tự động thử lại: một lần thử lại sẽ xoay vòng lần thứ hai và vô hiệu hóa mã bí mật mà lần thử đầu tiên đã trả về.
Những gì bạn có thể đăng ký
WEBHOOK_EVENTS được export để bạn có thể hiển thị danh sách. Các sự kiện là sự kiện của **hộp thư**, không phải của API này: email.received được kích hoạt khi thư đến trong ứng dụng, còn email.sent được kích hoạt khi trình soạn thư gửi một thư. Đăng ký không đồng nghĩa với việc theo dõi lưu lượng API của chính bạn.
Kiểm chứng rằng nó hoạt động
const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)responseCode là null nghĩa là hoàn toàn không có phản hồi (lỗi DNS, TLS, hết thời gian chờ), một sự thật khác với một phản hồi trả về 0. Mỗi hàng mang attempt và maxAttempts, nên nhiều hàng có thể mô tả cùng một sự kiện: payload.id giống nhau giữa các hàng xác định sự kiện, còn số lần thử cho biết đó là lần thử thứ mấy.
Tham số: webhooks.create
urlstringbắt buộc- Nơi các lần gửi được POST tới. Chỉ chấp nhận HTTPS, và host không được là `localhost`, tên `.localhost`/`.local`/`.internal`, hoặc địa chỉ IP dạng literal thuộc loopback, mạng riêng, CGNAT hay link-local. Đây là một yêu cầu fetch phía máy chủ tới địa chỉ do bạn cung cấp, nên các trường hợp đó trả về 422 trên `url`; việc kiểm tra đọc hostname đúng như đã viết và không bao giờ phân giải DNS. Giá trị được lưu là kết quả tuần tự hóa của trình phân tích URL từ những gì bạn gửi, nên `https://acme.com` được đọc lại thành `https://acme.com/`.
eventTypesWebhookEvent[]- Những sự kiện nào được gửi tới endpoint này: bất kỳ tên nào trong `WEBHOOK_EVENTS`. `POST /webhooks` giới hạn mảng ở số lượng sự kiện hiện có, nên vượt quá dù chỉ một phần tử sẽ trả về 422 trên `eventTypes`; `PATCH` thì không giới hạn. Chỉ độ dài bị giới hạn, và một tên lặp lại được lưu và đọc lại đúng như bạn đã gửi. Nếu bỏ qua hoặc để trống, giá trị được lưu là danh sách rỗng, đó là lý do nó được đọc lại thành `['*']`, và nó có nghĩa là mọi sự kiện `email.*` trừ `email.replied`, hiện tại là mười bốn sự kiện, và không bao giờ bao gồm các nhóm sự kiện domain hay suppression. Một nhóm được thêm sau này sẽ không bao giờ được gửi tới endpoint không chỉ định nó, nên một tích hợp không thể bắt đầu nhận một cấu trúc dữ liệu chưa từng thấy chỉ vì một bản phát hành mới.
descriptionstring- Nhãn cho endpoint, tối đa 200 ký tự, để danh sách webhook hiển thị dưới dạng tên thay vì một cột URL. Nếu bỏ qua, giá trị được lưu và trả về là null.
Phản hồi: CreatedWebhookResource
object'webhook'- Luôn là `'webhook'`, cùng giá trị phân biệt mà một thao tác đọc thông thường trả về, vì mã bí mật chỉ là một khóa bổ sung trên cấu trúc thông thường chứ không phải một kiểu đối tượng riêng. Việc có `secret` hay không được quyết định bởi phương thức bạn đã gọi, không phải bởi trường này.
idstring- Định danh của endpoint: `whe_` theo sau là 24 ký tự hex. Mọi lệnh gọi webhook khác đều nhận giá trị này: `get`, `update`, `delete`, `rotateSecret`, `test` và `listDeliveries`.
urlstring- Endpoint như đã được lưu, sau khi vượt qua các bước kiểm tra HTTPS và host bị chặn. Đây là URL đã được phân tích và tuần tự hóa lại, vì vậy hãy so sánh với giá trị này thay vì với chuỗi bạn đã gửi.
descriptionstring | null- Nhãn bạn đã đặt, hoặc null nếu bạn không đặt. Một `update` gửi null tường minh sẽ xóa nhãn về null.
eventTypesWebhookEvent[] | ['*']- Các sự kiện đã đăng ký, hoặc `['*']` khi endpoint không chỉ định sự kiện nào. `['*']` là cách một danh sách rỗng đã lưu được hiển thị khi đọc và không thể gửi lại, và nó đại diện cho mười ba sự kiện thư chứ không phải toàn bộ danh mục. `create` và `update` chỉ chấp nhận tên sự kiện dạng literal.
enabledboolean- Có thực hiện gửi hay không; một endpoint bị vô hiệu hóa sẽ bị bỏ qua khi phát sự kiện và vẫn giữ mã bí mật cùng lịch sử gửi của nó. Ở đây luôn là true, vì `WebhookCreate` không có `enabled`, chỉ `WebhookPatch` mới có.
lastDeliveryAtstring | null- Dấu thời gian ISO 8601 của LẦN THỬ gửi gần nhất, không phải lần thành công gần nhất. Nó cũng được ghi sau một POST thất bại, nên nó cho bạn biết endpoint đã được thử, còn `listDeliveries` cho bạn biết kết quả ra sao. Là null cho đến lần thử đầu tiên, do đó luôn là null trong `create`.
createdAtstring- Dấu thời gian ISO 8601 khi endpoint được đăng ký. `list` trả về các endpoint theo thứ tự mới nhất trước dựa trên trường này.
secretstring- Khóa HMAC-SHA-256 dùng để ký `X-OpenEmail-Signature` của mỗi lần gửi: `whsec_` theo sau là 32 byte ngẫu nhiên ở dạng base64url, và là giá trị bạn truyền cho `verifyWebhookSignature`. Chỉ được trả về bởi `create` và `rotateSecret`, không bởi bất kỳ lệnh nào khác. Thao tác đọc không bao giờ trả lại nó, vì vậy hãy lưu ngay; một mã bí mật bị mất chỉ có thể được thay thế bằng `rotateSecret`, và thao tác này vô hiệu hóa mã cũ ngay lập tức.