Webhook tuỳ chỉnh tới hệ thống của bạn

Webhook tuỳ chỉnh là cách đơn giản nhất để đưa giao dịch vào ERP, phần mềm bán hàng hoặc hệ thống riêng của bạn: Dòng Tiền Pro gọi một địa chỉ HTTPS của bạn mỗi khi có sự kiện. Màn Tích hợp dùng chung cơ chế ký, gửi lại và kiểm tra địa chỉ với Webhooks dành cho nhà phát triển, nên trang này tập trung vào việc cấu hình và vận hành.

Thiết lập

1. Vào Tích hợp, thêm tích hợp Webhook tuỳ chỉnh, nhập địa chỉ HTTPS nhận sự kiện.

2. Lưu bí mật ký dạng whsec_… hiển thị một lần. Bạn dùng bí mật này để kiểm tra chữ ký ở phía nhận.

3. Tạo quy tắc: chọn sự kiện và bộ lọc (tài khoản, chiều tiền, khoảng số tiền, mã số thuế, chỉ giao dịch có mã DTP, mẫu mã đơn). Bộ lọc được áp trước khi tạo lần gửi, nên sự kiện không khớp không sinh lần gửi nào.

4. Bấm Gửi thử để nhận một sự kiện thử và kiểm tra chữ ký ở phía bạn, rồi bật tích hợp.

Chỉ chấp nhận địa chỉ https công khai; địa chỉ nội bộ hoặc IP trần bị chặn. Để thử trên máy của bạn, dùng dtp listen như hướng dẫn ở sandbox.

Chữ ký và nội dung

Mỗi lần gọi theo chuẩn Standard Webhooks, mang ba tiêu đề:

webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1767225600
webhook-signature: v1,<chữ ký base64>

Bạn dùng webhook-id để loại sự kiện trùng và webhook-timestamp để từ chối yêu cầu quá cũ. Chữ ký tính từ bí mật whsec_…, mã, dấu thời gian và thân gửi nguyên văn. Bạn nên dùng thư viện standardwebhooks hoặc đoạn mã mẫu ở trang chữ ký và xác minh thay vì tự viết; SDK hiện chưa có hàm xác minh webhook riêng.

Sự kiện được gửi ít nhất một lần, nên phía nhận phải chịu được việc nhận trùng: dùng webhook-id hoặc mã giao dịch để loại trùng.

Thử lại và nhật ký

Phía nhận trả mã 2xx trong thời hạn quy định thì lần gửi được tính là thành công. Lỗi khác được thử lại theo lịch tăng dần; chi tiết lịch và quy tắc nằm ở thử lại. Nhật ký giao hàng hiện từng lần gửi, mã phản hồi và độ trễ; bạn gửi lại một hoặc nhiều lần gửi thất bại. Nếu địa chỉ của bạn lỗi liên tục, tích hợp chuyển sang suy giảm rồi lỗi, và bạn nhận thông báo.

Chỉ giao dịch Đã xác thực được gửi theo mặc định; sự kiện Tạm tính chỉ được gửi khi bạn bật tuỳ chọn tương ứng. Nhãn Đã xác thực là xác thực nguồn, không phải ngân hàng xác nhận quyết toán.

Thứ tự sự kiện không đảm bảo

Sự kiện có thể đến không theo thứ tự. Hãy dùng dấu thời gian và mã giao dịch trong thân để xử lý đúng thứ tự thay vì dựa vào thứ tự nhận; xem thứ tự và trùng lặp.