Webhook

Hensa gửi một POST JSON tới URL của bạn mỗi khi có sự kiện. Mọi webhook đều có chữ ký – luôn xác thực trước khi tin dữ liệu.

Sự kiện

• bank_transaction.createdCó tiền vào tài khoản đã liên kết (mọi khoản, kể cả không gắn với đơn).data BankTransaction
• payment_request.paidYêu cầu thanh toán đã được trả đủ – đây là sự kiện để giao hàng / xác nhận đơn.data PaymentRequest
• payment_request.partially_paidKhách chuyển thiếu so với yêu cầu. Chưa giao hàng – báo khách chuyển phần còn lại hoặc xử lý thủ công. Khi đủ tiền sẽ có `payment_request.paid`.data PaymentRequest
• payment_request.expiredHết hạn mà chưa được trả. Nhả hàng đang giữ hoặc tạo mã mới.data PaymentRequest
• bank_connection.status_changedKết nối ngân hàng lỗi hoặc được khôi phục. Tạm dừng nhận chuyển khoản nếu cần.data BankConnectionStatus

Payload

Mọi sự kiện có cùng một “phong bì”:

{
  "id": "evt_01JD7QB2S8E6H4N1P9C3V7K5TQ",
  "type": "payment_request.paid",
  "createdAt": "2026-11-03T08:03:12Z",
  "data": {
    "id": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
    "amount": 150000,
    "currency": "VND",
    "referenceCode": "LK7F3K9",
    "status": "paid",
    "externalOrderRef": "DH-1024",
    "…": "…"
  }
}

Trường	Ý nghĩa
id	ID sự kiện evt_… – dùng để chống trùng
type	Loại sự kiện
createdAt	Thời điểm sự kiện xảy ra
data	Đối tượng tại thời điểm đó (xem API Reference)

Header kèm theo:

Hensa-Signature: t=1762156992,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Trả lời Hensa

• Trả mã 2xx trong 10 giây. Mọi mã khác (hoặc quá thời gian) được tính là lỗi và sẽ được thử lại.
• Việc nặng (gửi email, gọi đơn vị vận chuyển…) → đưa vào hàng đợi, trả 200 ngay.
• Không cần trả nội dung.

Thử lại

Lần gửi lỗi được thử lại theo lịch cố định – tổng 8 lần trong khoảng 45 giờ:

Lần gửi	Chờ sau lần trước	Tính từ lần đầu
1	—	0
2	1 phút	1 phút
3	5 phút	6 phút
4	30 phút	36 phút
5	2 giờ	2.6 giờ
6	6 giờ	8.6 giờ
7	12 giờ	20.6 giờ
8	24 giờ	44.6 giờ

Hensa không bao giờ tắt webhook của bạn trong im lặng:

• Sau 3 lần lỗi liên tiếp: endpoint chuyển sang failing, Hensa gửi email cho chủ tài khoản và người quản trị kỹ thuật.
• Chỉ sau 7 ngày lỗi liên tục endpoint mới bị tạm dừng (disabled) – kèm email báo trước.
• Mọi sự kiện được giữ 30 ngày – bạn gửi lại được bất kỳ lúc nào, kể cả những sự kiện phát sinh lúc endpoint bị dừng.

Xử lý trùng lặp

Cùng một sự kiện có thể đến nhiều lần (thử lại, gửi lại thủ công, mạng chập chờn). Hãy ghi lại event.id đã xử lý và bỏ qua nếu gặp lại:

-- Một bảng nhỏ, ràng buộc UNIQUE làm phần khó
CREATE TABLE processed_hensa_events (event_id text PRIMARY KEY, processed_at timestamptz DEFAULT now());

Thứ tự

Hensa không đảm bảo thứ tự giữa các sự kiện. Đừng giả định bank_transaction.created luôn đến trước payment_request.paid – luôn đọc trạng thái trong data (hoặc gọi API lấy bản mới nhất).

Gửi lại

• Dashboard › Developer › Webhook › Lịch sử gửi → “Gửi lại” từng sự kiện.
• Hoặc API: POST /webhook_deliveries/{id}/redeliver.
• Gửi sự kiện thử: POST /webhook_endpoints/{id}/test hoặc nút “Gửi sự kiện thử” – nhận ngay một sự kiện mẫu đã ký để kiểm tra code.

Bảo mật URL

• Chỉ chấp nhận HTTPS công khai. Địa chỉ nội bộ (localhost, 10.x, 192.168.x…) bị từ chối.
• Thêm một đoạn khó đoán vào đường dẫn (vd. /webhooks/hensa/8f3k…) là lớp bảo vệ phụ – không thay thế cho việc xác thực chữ ký.

Phát triển trên máy cá nhân

Dùng ngrok hoặc Cloudflare Tunnel để có URL HTTPS trỏ về localhost. Hensa đang phát triển CLI hensa listen để chuyển webhook về máy bạn mà không cần công cụ ngoài.