Sự kiện webhook

Tham chiếu

Dành cho:: Nhà phát triển
Cần quyền:: webhooks:manage
Trong ứng dụng:: Cài đặt, rồi Webhook

Trang này liệt kê các loại sự kiện webhook mà một endpoint trong Cài đặt, rồi Webhook có thể đăng ký nhận, và envelope mà mọi lần gửi đều dùng. Nhận webhook hướng dẫn cách tạo endpoint và xác minh chữ ký.

Envelope

Mỗi lần gửi là một yêu cầu POST có nội dung JSON gồm năm trường:

Trường	Giá trị
`id`	ID sự kiện (UUID). Mọi endpoint nhận sự kiện đều nhận cùng một ID; hãy dùng ID này để bỏ qua bản trùng.
`type`	Loại sự kiện, ví dụ `email.bounced`.
`created_at`	Thời điểm sự kiện xảy ra, theo UTC (RFC 3339).
`workspace`	Slug của không gian làm việc.
`data`	Payload của sự kiện. Cấu trúc phụ thuộc vào loại sự kiện; sáu sự kiện mà các tích hợp dùng có payload mẫu trong hàng của chúng bên dưới.

Kiểm thử một endpoint sẽ gửi sự kiện webhook.test:

{
  "id": "01934f6e-8b2a-7c3d-9e4f-5a6b7c8d9e0f",
  "type": "webhook.test",
  "created_at": "2026-10-22T09:30:00.482913Z",
  "workspace": "acme-newsletter",
  "data": {
    "message": "Test event from ReputeCast. Verify the signature, then answer 2xx."
  }
}

Header	Giá trị
`Content-Type`	`application/json`
`User-Agent`	`ReputeCast-Webhooks/<version>`
`X-ReputeCast-Event`	Loại sự kiện.
`X-ReputeCast-Delivery`	ID lần gửi: mỗi cặp endpoint và sự kiện có một ID, không đổi qua các lần thử lại.
`X-ReputeCast-Timestamp`	Thời gian Unix tính bằng giây khi lần thử này được thực hiện.
`X-ReputeCast-Signature`	HMAC-SHA256 dạng hex chữ thường của `<timestamp>.<raw body>`, với khóa là toàn bộ chuỗi khóa bí mật `whsec_…`. Hãy từ chối timestamp lệch quá 5 phút.

Gửi và thử lại

Câu trả lời 2xx trong vòng 10 giây được tính là đã gửi thành công. Mọi trạng thái khác, hết thời gian chờ hoặc lỗi kết nối đều được thử lại.
Một sự kiện được thử tối đa 8 lần, chờ 1, 2, 4, 8, 30, 90 và 225 phút giữa các lần (tổng cộng khoảng sáu giờ). Sau lần thất bại thứ tám, sự kiện chuyển vào hàng đợi dead-letter, nơi bạn có thể phát lại sự kiện.
Endpoint đang tạm dừng vẫn tiếp tục xếp hàng sự kiện; khi bạn tiếp tục endpoint, các sự kiện đang xếp hàng được gửi theo thứ tự.
Sự kiện webhook.test chỉ được thử một lần và không bao giờ được thử lại.

Đăng ký nhận sự kiện

Một endpoint đăng ký từ 1 đến 40 mục. Mỗi mục là một loại sự kiện cụ thể (email.bounced), mọi sự kiện của một nhóm (email.*, khớp phần trước dấu chấm đầu tiên) hoặc mọi sự kiện (*).

Liên hệ

Sự kiện	Mô tả
`contact.subscribed`	Một liên hệ đã tham gia danh sách (sau bước xác nhận hai bước nếu đang bật). Payload mẫu `{ "company": "", "contact_id": "0192a4c1-7d4e-7c1e-9a40-3f1b2c8d5e01", "country": "MX", "email": "[email protected]", "fields": { "plan": "Team" }, "first_name": "Lucía", "language": "es-MX", "last_name": "Fernández", "list_id": "0192a4c1-0000-7000-8000-00000000b3a1", "list_name": "Weekly Digest", "lists": [ { "id": "0192a4c1-0000-7000-8000-00000000b3a1", "name": "Weekly Digest", "status": "subscribed" } ], "source": "form", "status": "active", "tags": [ "beta-applicant" ] }`
`contact.unsubscribed`	Một liên hệ đã rời danh sách hoặc hủy đăng ký mọi thứ. Payload mẫu `{ "company": "", "contact_id": "0192a4c1-7d4e-7c1e-9a40-3f1b2c8d5e01", "country": "MX", "email": "[email protected]", "fields": { "plan": "Team" }, "first_name": "Lucía", "language": "es-MX", "last_name": "Fernández", "list_id": "0192a4c1-0000-7000-8000-00000000b3a1", "list_name": "Weekly Digest", "lists": [ { "id": "0192a4c1-0000-7000-8000-00000000b3a1", "name": "Weekly Digest", "status": "subscribed" } ], "source": "form", "status": "active", "tags": [ "beta-applicant" ] }`
`contact.updated`	Trường, thẻ hoặc tùy chọn đã thay đổi. Payload mẫu `{ "changed": [ "language", "tags" ], "company": "", "contact_id": "0192a4c1-7d4e-7c1e-9a40-3f1b2c8d5e01", "country": "MX", "email": "[email protected]", "fields": { "plan": "Team" }, "first_name": "Lucía", "language": "es-MX", "last_name": "Fernández", "lists": [ { "id": "0192a4c1-0000-7000-8000-00000000b3a1", "name": "Weekly Digest", "status": "subscribed" } ], "status": "active", "tags": [ "beta-applicant" ] }`
`contact.erased`	Dữ liệu cá nhân đã bị xóa vĩnh viễn.

Email

Sự kiện	Mô tả
`email.sent`	Một nhà cung cấp gửi thư đã nhận một thư.
`email.delivered`	Nhà cung cấp hộp thư đã nhận thư.
`email.deferred`	Việc gửi bị hoãn và sẽ được thử lại.
`email.bounced`	Thư trả lại vĩnh viễn hoặc tạm thời, kèm mã gốc của nhà cung cấp.
`email.complained`	Người nhận đã đánh dấu thư là spam.
`email.opened`	Một lượt mở bởi người đọc (lượt mở tự động có machine: true).
`email.clicked`	Một liên kết được theo dõi đã được nhấp.

Chiến dịch

Sự kiện	Mô tả
`campaign.scheduled`	Một chiến dịch đã được lên lịch.
`campaign.started`	Một lần gửi đã bắt đầu.
`campaign.paused`	Một lần gửi đã tạm dừng, do một người hoặc tự động.
`campaign.resumed`	Một lần gửi đang tạm dừng đã tiếp tục.
`campaign.completed`	Một lần gửi đã hoàn tất. Payload mẫu `{ "campaign_id": "0192a4c1-0000-7000-8000-0000000c0142", "completed_at": "2026-10-14T13:41:00Z", "delivered": 31352, "name": "Weekly Digest #142", "sent": 31604, "started_at": "2026-10-14T13:00:00Z", "status": "sent", "subject": "Three launches, one deprecation, and the roadmap for Q4" }`

Phê duyệt

Sự kiện	Mô tả
`approval.requested`	Một lần gửi cần phê duyệt.
`approval.decided`	Một lần gửi đã được phê duyệt, bị từ chối hoặc bị trả lại để sửa.

Nhà cung cấp gửi thư

Sự kiện	Mô tả
`provider.down`	Một nhà cung cấp gửi thư đang lỗi hoặc không kết nối được.
`provider.recovered`	Một nhà cung cấp gửi thư đã ổn định trở lại.

Tự động hóa

Sự kiện	Mô tả
`automation.published`	Một quy trình tự động đã được xuất bản.

Thư giao dịch

Sự kiện	Mô tả
`message.sent`	Một nhà cung cấp gửi thư đã nhận một thư giao dịch.
`message.delivered`	Nhà cung cấp hộp thư đã nhận thư.
`message.deferred`	Việc gửi bị hoãn và sẽ được thử lại.
`message.bounced`	Thư trả lại vĩnh viễn hoặc tạm thời, kèm mã gốc của nhà cung cấp. Payload mẫu `{ "message_id": "msg_01J9ZK7Q2X8M", "metadata": { "user_id": "u_8812" }, "provider": "postmark", "reason": "550 5.1.1 The email account that you tried to reach does not exist", "subtype": "hard", "tags": [ "auth" ], "template": "password-reset", "to": "[email protected]" }`
`message.complained`	Người nhận đã đánh dấu thư là spam.
`message.rejected`	Bị dừng trước khi gửi: bị chặn gửi hoặc đã từ chối nhận loại thư này.
`message.failed`	Mọi nhà cung cấp trong tuyến đều thất bại sau các lần thử lại.
`message.opened`	Thư đã được mở (mẫu có theo dõi lượt mở).
`message.clicked`	Một liên kết được theo dõi đã được nhấp (mẫu có theo dõi lượt nhấp).

Biểu mẫu

Sự kiện Mô tả

Sự kiện	Mô tả
`form.submitted`	Một lượt đăng ký đã được xác nhận (ngay lập tức với xác nhận một bước), kèm biểu mẫu và các câu trả lời. Payload mẫu `{ "answers": { "email": "[email protected]", "first_name": "Lucía" }, "confirmed_at": "2026-10-03T14:05:40Z", "consent_text": "I agree to receive emails from Acme. Unsubscribe any time with one click.", "contact_id": "0192a4c1-7d4e-7c1e-9a40-3f1b2c8d5e01", "double_opt_in": true, "email": "[email protected]", "form_id": "frm_8c2e1a", "form_name": "Newsletter signup", "language": "es", "lists": [ "Weekly Digest" ], "submitted_at": "2026-10-03T14:02:11Z" }`

form.submitted

Một lượt đăng ký đã được xác nhận (ngay lập tức với xác nhận một bước), kèm biểu mẫu và các câu trả lời.

Payload mẫu

{
  "answers": {
    "email": "[email protected]",
    "first_name": "Lucía"
  },
  "confirmed_at": "2026-10-03T14:05:40Z",
  "consent_text": "I agree to receive emails from Acme. Unsubscribe any time with one click.",
  "contact_id": "0192a4c1-7d4e-7c1e-9a40-3f1b2c8d5e01",
  "double_opt_in": true,
  "email": "[email protected]",
  "form_id": "frm_8c2e1a",
  "form_name": "Newsletter signup",
  "language": "es",
  "lists": [
    "Weekly Digest"
  ],
  "submitted_at": "2026-10-03T14:02:11Z"
}

Giới thiệu

Sự kiện	Mô tả
`referral.counted`	Một lượt giới thiệu đã được tính: người đăng ký đã xác nhận và ở lại hết thời gian chờ.
`referral.held`	Một lượt giới thiệu bị tạm giữ để duyệt theo một quy tắc nghi vấn.
`referral.not_counted`	Một lượt giới thiệu không được tính, kèm lý do.
`referral.milestone_reached`	Một người giới thiệu đã đạt một mốc thưởng.
`referral.reward_sent`	Một phần thưởng đã được gửi cho người giới thiệu (một tệp tải xuống, một mã, một liên kết nhận thưởng).
`referral.reward_failed`	Một phần thưởng qua webhook thất bại sau 6 giờ thử lại.

Hội viên trả phí

Sự kiện	Mô tả
`subscription.trial_started`	Một thuê bao trả phí đã bắt đầu với thời gian dùng thử miễn phí.
`subscription.started`	Một thuê bao trả phí đã bắt đầu và khoản thanh toán đầu tiên đã được thực hiện.
`subscription.renewed`	Một thuê bao đã gia hạn và khoản thanh toán đã thành công.
`subscription.payment_failed`	Một khoản thanh toán thất bại; nhà cung cấp sẽ thử lại.
`subscription.cancel_scheduled`	Một thuê bao sẽ kết thúc vào cuối kỳ hiện tại.
`subscription.ended`	Quyền truy cập trả phí đã kết thúc: đã hủy, chưa thanh toán, hoặc thời gian dùng thử kết thúc mà không thanh toán.
`subscription.changed`	Một hội viên trả phí đã đổi gói hoặc chuyển giữa theo tháng và theo năm.
`access.complimentary_granted`	Một thành viên trong nhóm đã cấp quyền truy cập miễn phí.
`access.complimentary_ended`	Quyền truy cập miễn phí đã kết thúc hoặc bị gỡ.
`gift.purchased`	Một người đọc đã mua thuê bao làm quà tặng.
`gift.redeemed`	Người nhận đã dùng một quà tặng.
`conversion.recorded`	Một lượt nâng cấp hoặc chuyển đổi đã được ghi nhận cho một email.

Sản phẩm và đơn hàng

Sự kiện	Mô tả
`order.paid`	Người mua đã thanh toán cho một sản phẩm số; email giao hàng đang được gửi.
`order.refunded`	Một đơn hàng đã được hoàn tiền trong Stripe, toàn bộ hoặc một phần.
`order.disputed`	Người mua đã mở tranh chấp với ngân hàng về khoản thanh toán của một đơn hàng.

Thông báo đẩy

Sự kiện	Mô tả
`push.clicked`	Một người đọc đã nhấp vào thông báo hoặc một nút của thông báo (mỗi thông báo một lần).

SMS

Sự kiện	Mô tả
`sms.delivered`	Nhà mạng đã chuyển phát một tin nhắn.
`sms.failed`	Một tin nhắn gửi thất bại, kèm lý do và mã riêng của nhà cung cấp.
`sms.clicked`	Một người đã nhấp vào liên kết rút gọn trong tin nhắn (bản xem trước liên kết có machine: true).
`sms.opted_out`	Một số đã nhắn STOP: sự đồng ý nhận SMS bị rút ở mọi danh sách.
`sms.opted_in`	Một số đã nhắn START: các sự đồng ý mà STOP đã gỡ được khôi phục.
`sms.replied`	Một tin trả lời không phải từ khóa, kèm nội dung.

Trang web

Sự kiện	Mô tả
`post.published`	Một bài viết đã lên website, do một người đăng, đến giờ đã hẹn hoặc cùng lúc gửi chiến dịch.
`post.unpublished`	Một bài viết đã bị gỡ khỏi website hoặc bị xóa.

Sự kiện	Mô tả
`whatsapp.delivered`	Meta đã chuyển phát một tin nhắn WhatsApp.
`whatsapp.read`	Một người đã đọc tin nhắn WhatsApp (chỉ với những người chia sẻ thông báo đã đọc).
`whatsapp.failed`	Một tin nhắn WhatsApp gửi thất bại, kèm lý do và mã của Meta.
`whatsapp.replied`	Một người đã viết hoặc chạm vào nút trả lời nhanh: khung 24 giờ được mở.
`whatsapp.opted_out`	Một số đã gửi từ khóa hủy nhận: sự đồng ý nhận WhatsApp bị rút ở mọi danh sách.
`whatsapp.opted_in`	Một số đã gửi từ khóa đăng ký nhận: các sự đồng ý mà lần hủy nhận đã gỡ được khôi phục.
`whatsapp.template_status`	Meta đã phê duyệt, từ chối, tạm dừng hoặc vô hiệu hóa một mẫu.

Liên quan

Nhận webhook có mã xác minh chữ ký bằng Node.js, Python, Go và PHP.
Xây dựng tích hợp trình bày REST hook mà các công cụ như Zapier dùng để đăng ký nhận sự kiện.
Quyền và vai trò liệt kê ai có thể quản lý endpoint webhook.
Giới hạn và mặc định liệt kê các giới hạn của webhook.