Webhooks API

Quản lý webhook rule của bạn. Mỗi rule là 1 endpoint nhận POST khi có giao dịch khớp filter (ngân hàng, loại, min amount...).

Xem cách xác thực — giống Transactions API (JWT hoặc API key).

---

Payload BeePay gửi đến endpoint của bạn

Header:

Content-Type: application/json
X-Webhook-Signature: sha256=<HMAC của body với secret_key>
X-Webhook-Source: beepay

payload_format: standard (mặc định)

{
  "event": "bank_transaction",
  "bank_code": "MB",
  "bank_name": "MB Bank",
  "transaction_type": "credit",
  "amount": "500000.00",
  "currency": "VND",
  "balance_after": null,
  "account_number": "008000888",
  "transaction_ref": "FT26111330819043",
  "transaction_date": "2026-04-21T08:25:04.000Z",
  "description": "BEEPAY42 thanh toan",
  "counterpart_name": "NGUYEN VAN A",
  "order_id": "BEEPAY42",
  "transaction_id": 5669,
  "timestamp": 1745227504
}

payload_format: woocommerce

Compatible với WooCommerce webhook format:

{
  "order_id": "BEEPAY42",
  "payment_method": "bank_transfer",
  "transaction_id": "FT26111330819043",
  "amount": "500000.00",
  "currency": "VND",
  "status": "completed",
  "description": "BEEPAY42 thanh toan",
  "note": "MB Bank received 500,000 VND - Ref: FT26...",
  "bank_code": "MB",
  "bank_name": "MB Bank",
  "transaction_type": "credit",
  "payer_name": "NGUYEN VAN A",
  "timestamp": 1745227504
}

Verify signature (production bắt buộc)

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.BEEPAY_WEBHOOK_SECRET)
  .update(rawBody)          // verify trên raw bytes, không parse JSON trước
  .digest('hex')

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).end('Invalid signature')
}

Xem thêm: Retry & Signature.

---

List rules

GET /api/webhooks

{
  "success": true,
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "system_id": 3,
      "system_name": "My Shop WooCommerce",
      "name": "Production webhook",
      "url": "https://yourshop.com/beepay-webhook",
      "secret_key": "a1b2c3d4...",
      "http_method": "POST",
      "filter_banks": ["MB", "VCB"],
      "filter_type": "credit",
      "min_amount": 10000,
      "payload_format": "standard",
      "is_active": 1,
      "is_auto": 0,
      "created_at": "2026-04-20T..."
    }
  ]
}

Create rule

POST /api/webhooks
Content-Type: application/json

{
  "name": "Production shop",
  "url": "https://yourshop.com/beepay-webhook",
  "system_id": 3,
  "http_method": "POST",
  "filter_banks": ["MB", "VCB"],
  "filter_type": "credit",
  "min_amount": 10000,
  "payload_format": "standard"
}

Fields

Field	Loại	Default	Mô tả
name	string	—	Tên gợi nhớ
url	string	—	HTTPS URL nhận webhook
system_id	int?	null	Link với connected_system (optional)
http_method	string	POST	POST / PUT
filter_banks	array	[]	Chỉ bắn cho ngân hàng trong list. [] = tất cả
filter_type	string	both	credit / debit / both
min_amount	int?	null	Chỉ bắn nếu amount ≥ giá trị này
payload_format	string	standard	standard / woocommerce / custom
custom_template	string?	null	JSON template khi payload_format=custom

Response trả record đã tạo, kèm secret_key auto-generate (48 hex chars).

Secret

Copy secret_key ngay lúc nhìn thấy. Không có endpoint rotate riêng — nếu muốn đổi secret, xoá rule và tạo lại.

Giới hạn theo gói

Gói	Max webhook rules
Free	1
Basic	3
Advanced	10
Pro	Không giới hạn

Vượt → 403:

{ "success": false, "error": "WEBHOOK_LIMIT_REACHED", "plan": "Free", "limit": 1 }

Update rule

PUT /api/webhooks/:id

Body giống Create. Có thể partial update chỉ is_active:

{ "is_active": 0 }

Test webhook

POST /api/webhooks/:id/test

BeePay gửi payload mẫu đến URL của rule — không phải payload thật:

{
  "event": "test",
  "bank_code": "VCB",
  "bank_name": "Vietcombank",
  "transaction_type": "credit",
  "amount": 100000,
  "currency": "VND",
  "description": "Test webhook from BeePay",
  "timestamp": 1745227504
}

Response (thành công):

{
  "success": true,
  "http_code": 200,
  "response_time_ms": 142,
  "response_body": "{\"ok\":true}"
}

Response (lỗi):

{
  "success": false,
  "http_code": 500,
  "error": "Request failed with status code 500"
}

Logs delivery

GET /api/webhooks/:id/logs?page=1

Lịch sử bắn webhook (20 dòng/trang) kèm info giao dịch:

{
  "success": true,
  "data": [
    {
      "id": 999,
      "webhook_rule_id": 1,
      "transaction_id": 5669,
      "bank_code": "MB",
      "amount": "500000.00",
      "transaction_type": "credit",
      "http_status": 200,
      "response_body": "{\"ok\":true}",
      "attempt": 1,
      "sent_at": "2026-04-21T08:25:06.000Z",
      "created_at": "..."
    }
  ],
  "total": 123,
  "page": 1,
  "limit": 20
}

Bulk retry

POST /api/webhooks/bulk-retry

Queue retry tối đa 100 giao dịch đang webhook_status=failed trong 7 ngày gần nhất của user.

{ "success": true, "count": 42 }

Delete rule

DELETE /api/webhooks/:id

Webhook tự động (is_auto)

Webhook được tạo tự động khi kết nối plugin WooCommerce / Masteriyo (có is_auto=1) không thể xoá qua API này (trả 403). Muốn xoá → disconnect plugin trong Dashboard → Kết nối & Thanh toán.