Webhook riêng gửi sự kiện giao dịch tới địa chỉ HTTPS do bạn chỉ định. Mỗi yêu cầu được ký theo Standard Webhooks, nên bạn kiểm chữ ký bằng bất kỳ thư viện Standard Webhooks nào. Đây là cách nối Dòng Tiền Pro với phần mềm nội bộ hoặc nền tảng không có kết nối sẵn.
Ba header của mỗi yêu cầu
webhook-id: mã duy nhất của sự kiện, dùng để xử lý mỗi sự kiện đúng một lần.webhook-timestamp: thời điểm gửi, dùng để từ chối yêu cầu quá cũ.webhook-signature: chữ ký trên mã, thời điểm và thân yêu cầu.
Các bước
- Mở màn Tích hợp, chọn Webhook riêng.
- Nhập địa chỉ HTTPS của bạn.
- Bạn chọn sự kiện cần gửi và bộ lọc: tài khoản, chiều tiền vào hoặc ra, ngưỡng số tiền, mã số thuế. Mẫu tin tiếng Việt có sẵn và chỉnh được.
- Lưu khoá ký và cấu hình kiểm chữ ký ở máy chủ của bạn.
- Gửi thử, kiểm tra máy chủ trả mã 2xx, rồi bật.
Ví dụ kiểm chữ ký
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.DT_WEBHOOK_SECRET!);
// headers: webhook-id, webhook-timestamp, webhook-signature
const event = wh.verify(rawBody, headers);
Kiểm chữ ký trên thân yêu cầu gốc, trước khi phân tích JSON.
An toàn khi gửi
Địa chỉ đích phải là HTTPS. Hệ thống không theo chuyển hướng và chặn địa chỉ nội bộ, nên webhook không bị dùng để gọi vào mạng riêng. Mỗi lần gửi được ghi nhật ký; lần gửi lỗi được thử lại và bạn có thể gửi lại thủ công từng sự kiện.
“Đã xác thực”: xác thực nguồn, không phải ngân hàng xác nhận quyết toán.
Điều webhook không làm
- Không có định dạng webhook nào khác ngoài Standard Webhooks.
- Không nhận lệnh từ máy chủ của bạn; webhook chỉ gửi đi.
- Không chuyển tiền.
Câu hỏi thường gặp
Máy chủ của tôi ngừng vài giờ thì có mất sự kiện không?
Lần gửi lỗi được thử lại; sau đó bạn xem nhật ký giao hàng và gửi lại. Bạn cũng có thể gọi API để đồng bộ lại.
Một sự kiện có thể đến hai lần không?
Có thể, khi thử lại. Dùng webhook-id để bỏ qua sự kiện đã xử lý.
Có ví dụ cho ngôn ngữ khác không?
Thư viện Standard Webhooks có cho nhiều ngôn ngữ. Tài liệu đầy đủ ở docs.dongtien.pro.
