Cơ sở kiến thức

Webhook

Báo cho endpoint của bạn khi thư tới, thay vì bắt bạn phải liên tục hỏi.

Chi tiết

Dùng được ngay hôm nay từ Cài đặt → Webhook và qua API: đăng ký một endpoint https, chọn nó muốn nhận sự kiện nào trong hai mươi sự kiện, và sao chép phần bí mật ký whsec_, vốn chỉ hiển thị lúc tạo và lúc xoay vòng chứ không bao giờ hiện lại. Các lượt gửi đi là những yêu cầu POST có chữ ký thật, do chính hộp thư phát ra chứ không phải do một lệnh gọi API nào, nên chúng kích hoạt khi có thư tới và khi có lượt mở hay lượt bấm, bất kể thư được gửi từ đâu. Việc gửi thư kích hoạt sự kiện từ mọi bề mặt, còn trước kia thì chỉ từ một số: gửi qua API, MCP, một mẫu hay một quy tắc đều phát ra email.sent, trong khi một thư gửi từ trình soạn thư của chính ứng dụng thì không, vì trình soạn thư ghi thẳng vào hộp thư chứ không đi qua dịch vụ gửi vốn phát ra sự kiện đó. Nay sự kiện được phát ra tại chính hộp thư, nơi tất cả đều gặp nhau, nên soạn thư trong ứng dụng, hẹn lịch gửi vào thứ Ba và gọi API là ba cách gây ra cùng một webhook. Một lần gửi hoãn lại báo hai lần: email.scheduled hoặc email.queued khi được chấp nhận, email.sent khi nó thực sự đi, và email.cancelled nếu bạn rút lại trong khoảng giữa. Mười endpoint cho mỗi hộp thư, được áp dụng ở bất cứ nơi nào một endpoint được đăng ký chứ không chỉ trên màn hình này.
Các sự kiện chia thành ba họ. Mười lăm sự kiện nói về một thư: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (anh em với scheduled, dành cho hoàn tác gửi), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked và email.downloaded. email.sent nghĩa là dịch vụ gửi đã nhận thư, email.delivered nghĩa là máy chủ nhận đã nhận thư, còn email.delivery_delayed nghĩa là thư chưa tới nơi và vẫn đang được thử lại. email.replied phát ra cùng lúc với email.received khi thư đang tới là câu trả lời cho một thư đã có trong hộp thư, nên bên tiêu thụ muốn cả hai sẽ nhận được cả hai. email.downloaded phát ra khi một người tải một tệp đã đi kèm dưới dạng liên kết tải xuống, với cùng bộ phân loại giữ cho các trình quét và trình xem trước liên kết không bị tính vào, và nó không nêu tên người nhận nào, vì liên kết là như nhau với tất cả những người mà thư đã gửi tới. Ba sự kiện nói về một tên miền: domain.verified khi nó bắt đầu nhận thư, domain.sending_changed khi kết luận về khả năng gửi của nó thay đổi, và domain.deleted khi nó bị gỡ bỏ, dù là bạn yêu cầu hay bộ dọn dẹp bảy ngày đã loại nó vì chưa xác minh. Hai sự kiện nói về chính danh sách chặn gửi, vốn khác với email.suppressed: suppression.added khi một địa chỉ được đưa vào, suppression.removed khi một địa chỉ được cho phép trở lại. Không đăng ký sự kiện nào nghĩa là nhận mọi sự kiện về thư trừ email.replied, hôm nay là mười bốn sự kiện, và không bao giờ gồm một họ được thêm về sau, và API đọc lại điều đó thành ["*"]. Hãy nêu tên những sự kiện bạn muốn nếu bạn thích nói rõ ràng. Mỗi lượt gửi mang theo X-OpenEmail-Signature dưới dạng t=<unix>,v1=<hex>, một HMAC-SHA-256 trên dấu thời gian, một dấu chấm, và phần thân thô, cộng thêm X-OpenEmail-Event và X-OpenEmail-Delivery. Hãy xác minh dựa trên đúng chuỗi byte như khi nó tới: phân tích rồi tuần tự hóa lại sẽ sắp xếp lại các khóa và làm hỏng chữ ký. Cửa sổ chống phát lại 300 giây là phần bên nhận phải tự áp dụng, và bộ xác minh của SDK mặc định dùng nó.
Việc đăng ký bị từ chối với bất cứ thứ gì không phải https hoặc không định tuyến được công khai (loopback, RFC1918, link-local, CGNAT và các tương đương IPv6), và các chuyển hướng không được đi theo, nên một mã 3xx được ghi nhận là một lượt gửi thất bại chứ không bị đuổi theo sang nơi khác. Bên nhận có 5 giây, các endpoint được gửi song song nên mười endpoint vẫn chỉ tốn 5 giây chứ không phải 50, và những lần thử gần đây được liệt kê trên trang của endpoint đó kèm mã phản hồi và thời gian đã mất.
Mỗi lượt gửi được thử tối đa năm lần. Lần đầu đi ngay khi sự kiện xảy ra; một thất bại có khả năng tự hết được thử lại sau 1 phút, rồi 5, rồi 25, rồi 2 giờ, tức là trải một sự kiện ra khoảng hai tiếng rưỡi. Các lần thử lại được giữ như công việc bền vững chứ không phải trong bộ nhớ, nên một lần triển khai giữa khoảng thời gian đó không làm mất chúng. Chỉ những thất bại đáng lặp lại mới được lặp lại: hết thời gian chờ, kết nối bị từ chối, 408, 425, 429 hoặc bất kỳ mã 5xx nào. Bất kỳ mã 4xx nào khác đều là endpoint cố ý từ chối payload, và hỏi thêm bốn lần nữa sẽ là bốn lần tải cho cùng một câu trả lời. Id của sự kiện được tạo một lần và mọi lần thử đều mang nó trong X-OpenEmail-Delivery, nên một bên nhận thấy cùng một id hai lần có thể bỏ lần thứ hai thay vì xử lý hai lần. Sau khi 100 sự kiện liên tiếp thất bại ở mọi lần thử, endpoint bị vô hiệu hóa, không gian làm việc được gửi email báo, và lý do đọc được ngay trên chính endpoint đó. Một endpoint trả về 410 Gone bị vô hiệu hóa ngay lập tức.
Một endpoint thất bại 100 lần liên tiếp sẽ bị tắt đi chứ không bị gọi mãi mãi, và tất cả những ai có quyền truy cập webhook đều được gửi email báo: endpoint nào, lần thử cuối báo gì, và rằng không có gì được xếp hàng đợi trong lúc nó thất bại. Số đếm này là LIÊN TIẾP và bất kỳ lần gửi thành công nào cũng đặt lại nó, nên một buổi chiều tồi tệ hồi tháng Ba năm ngoái không thể cộng dồn thành một endpoint bị vô hiệu hóa hôm nay. Bật nó trở lại cũng xóa luôn số đếm. Bảng điều khiển phân biệt hai trạng thái đó chứ không chỉ hiển thị một nút gạt: một endpoint do bạn tắt trông khác với một endpoint do chúng tôi tắt.
Quản lý endpoint là một công việc với hai cửa vào. Qua API thì đó là POST /webhooks, lệnh patch, lệnh delete, rotate-secret, test và nhật ký gửi, mỗi thứ có một phương thức trong SDK; trong ứng dụng thì đó là Cài đặt → Webhook, thao tác trên cùng một sổ đăng ký chứ không phải một sổ thứ hai. Việc đọc được canh bởi webhooks:read, nên bất kỳ ai đang xây dựng một tích hợp đều có thể xem các endpoint và lịch sử gửi của chúng (endpoint nào đã kích hoạt, bên nhận trả lời gì, mất bao lâu) mà không cần là chủ sở hữu. Đăng ký, sửa, kiểm thử, xoay vòng và xóa đều cần webhooks:write VÀ quyền sở hữu hộp thư, trên cả hai bề mặt, và nửa thứ hai đó là có chủ ý: một endpoint không có trục địa chỉ, nên nó nhận mọi địa chỉ mà không gian làm việc nắm giữ kèm cả tiêu đề và người nhận, và không quyền nào có nghĩa là “được phép nhận tất cả những thứ đó”. Một vai trò chuyên xây tích hợp mà không đọc thư thì dùng một khóa không gian làm việc để điều khiển nó.