Webhooks

~4 phút đọc

Webhook cho phép Dòng Tiền Pro gọi tới máy chủ của bạn ngay khi có sự kiện, ví dụ một giao dịch vừa được xác thực nguồn, thay vì để bạn hỏi lại API liên tục. Dòng Tiền Pro chỉ dùng một định dạng duy nhất: Standard Webhooks. Bạn có thể dùng thư viện Standard Webhooks có sẵn của hầu hết ngôn ngữ để xác minh.

Tạo endpoint

Tạo và quản lý endpoint ở mục Webhooks của trang Nhà phát triển.

Nhập địa chỉ HTTPS nhận webhook, chọn công ty (hoặc tất cả công ty) và các loại sự kiện muốn nhận. Danh sách loại sự kiện sinh từ danh mục sự kiện.
Lưu lại secret whsec_… hiện ra một lần; dùng nó để xác minh chữ ký.
Bấm Gửi thử: endpoint nhận ngay một sự kiện ping mang nhãn [TEST] và bạn thấy mã HTTP, độ trễ cùng đoạn đầu phản hồi.

Địa chỉ endpoint phải là HTTPS, cổng 443 hoặc 8443, không chứa tên đăng nhập hay mật khẩu. Dòng Tiền Pro không gửi tới địa chỉ IP nội bộ, địa chỉ loopback hay các địa chỉ dịch vụ đám mây dành riêng, và không đi theo chuyển hướng: phản hồi 3xx được tính là giao thất bại.

Một lần giao

Mỗi lần giao là một yêu cầu POST với các header của chuẩn:

POST /hook HTTP/1.1
content-type: application/json
user-agent: DongTien-Webhooks/1.0
webhook-id: msg_0f5k2m9q4h7t3n8r6v1w0x5yze
webhook-timestamp: 1792377668
webhook-signature: v1,<base64>

Thân là phong bì sự kiện:

{
  "id": "evt_0f5k2m9q4h7t3n8r6v1w0x5yzd",
  "type": "transaction.confirmed",
  "api_version": "2026-10-19",
  "timestamp": "2026-10-19T02:41:08Z",
  "data": { "object": { "id": "tx_0f5k2m9q4h7t3n8r6v1w0x5yzd", "object": "transaction" } }
}

Trường	Ý nghĩa
`id`	Mã sự kiện `evt_…`, ổn định qua mọi lần thử lại.
`type`	Loại sự kiện, ví dụ `transaction.confirmed`.
`api_version`	Phiên bản API ghim ở endpoint; hình dạng `data` theo phiên bản này.
`timestamp`	Thời điểm sự kiện, RFC 3339 UTC.
`data.object`	Đối tượng của sự kiện (giao dịch, yêu cầu thanh toán, …). Số tài khoản luôn bị che còn bốn số cuối trừ khi endpoint bật gửi số đầy đủ.

Giao dịch ở trạng thái transaction.confirmed là giao dịch đã xác thực nguồn: xác thực nguồn, không phải ngân hàng xác nhận quyết toán. Sự kiện transaction.created có thể mang giao dịch còn tạm tính, nên hãy coi transaction.confirmed là tín hiệu tiền về.

Quy tắc xác nhận

Trả mã 2xx trong 10 giây là đã nhận. Xử lý nặng nên đưa vào hàng đợi của bạn và trả lời ngay.
Mọi mã khác, kể cả 3xx, 4xx, 5xx và hết thời gian chờ, bị thử lại theo lịch.
Trả 410 Gone báo rằng endpoint đã bị bỏ: Dòng Tiền Pro tắt endpoint ngay, không thử lại.
Vì Dòng Tiền Pro giao ít nhất một lần, cùng một sự kiện có thể tới nhiều lần và không đảm bảo thứ tự. Xem thứ tự và trùng lặp.

Lọc theo nội dung chuyển khoản

Với các sự kiện mang nội dung chuyển khoản, bạn có thể gắn cho endpoint một bộ lọc: chọn một mẫu đã lưu hoặc nhập trực tiếp một biểu thức chính quy RE2 dài tối đa 128 ký tự, không dùng lookaround hay backreference. Chỉ sự kiện có nội dung khớp mới được giao tới endpoint đó. Nút Gửi thử luôn giao, bất kể bộ lọc. Cách viết mẫu, ví dụ và bộ lọc chỉ mã DTP có ở trang lọc theo nội dung CK.

IP nguồn tĩnh

Mặc định webhook đi ra từ hạ tầng chung của Dòng Tiền Pro. Nếu máy chủ của bạn chỉ chấp nhận kết nối từ danh sách IP cho phép, chọn Egress: IP tĩnh ở endpoint: webhook khi đó đi qua một cụm máy riêng có địa chỉ IP cố định, tách biệt với các địa chỉ khác của Dòng Tiền Pro. Địa chỉ cụ thể được công bố khi tính năng phát hành; khi đó bạn thêm chúng vào danh sách cho phép trước khi bật chế độ này.

Chữ ký và xác minhThuật toán và ví dụ TypeScript, Python, PHP.

Thử lạiLịch 8 lần, tạm ngưng endpoint và phát lại.

Thứ tự và trùng lặpKhử trùng theo webhook-id.

Lọc theo nội dung CKChỉ nhận sự kiện có nội dung chuyển khoản khớp mẫu.

Danh mục sự kiệnMọi loại sự kiện và dữ liệu đi kèm.