API Webhook

API Reference Cập nhật: 23/03/2026

Webhook API

Quản lý webhook để nhận thông báo giao dịch tự động.

Danh sách Webhook

GET /api/v1/webhooks
Authorization: Bearer YOUR_API_KEY

Response

{
  "status": true,
  "messages": "Thành công",
  "webhooks": [
    {
      "id": 1,
      "name": "Webhook đơn hàng",
      "webhook_url": "https://your-domain.com/webhook",
      "bank_account_id": 2,
      "type": "ALL",
      "is_active": true,
      "created_at": "2026-03-22 12:36:42"
    }
  ]
}

Tạo Webhook

POST /api/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

Trường	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tên webhook
webhook_url	string	Có	URL nhận webhook (HTTPS khuyến nghị)
type	string	Có	`IN`, `OUT`, hoặc `ALL`
bank_account_id	integer	Không	ID tài khoản cụ thể. Bỏ qua = tất cả tài khoản.

Request mẫu

{
  "name": "Webhook đơn hàng",
  "webhook_url": "https://your-domain.com/webhook",
  "type": "ALL"
}

Response

{
  "status": true,
  "messages": "Tạo webhook thành công",
  "webhook": {
    "id": 2,
    "name": "Webhook đơn hàng",
    "webhook_url": "https://your-domain.com/webhook",
    "type": "ALL",
    "is_active": true,
    "created_at": "2026-03-23 07:00:00"
  },
  "secret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Quan trọng: Secret key chỉ hiển thị một lần duy nhất trong response tạo webhook. Hãy lưu lại ngay. Dùng để xác thực chữ ký X-Webhook-Signature.

Cập nhật Webhook

PUT /api/v1/webhooks/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

{
  "name": "Webhook cập nhật",
  "webhook_url": "https://new-domain.com/webhook",
  "type": "IN"
}

Chỉ gửi các trường muốn thay đổi.

Bật/Tắt Webhook

PATCH /api/v1/webhooks/{id}/toggle
Authorization: Bearer YOUR_API_KEY

Response

{
  "status": true,
  "messages": "Đã bật webhook",
  "webhook": { "id": 1, "is_active": true }
}

Xóa Webhook

DELETE /api/v1/webhooks/{id}
Authorization: Bearer YOUR_API_KEY

Response

{
  "status": true,
  "messages": "Đã xóa webhook"
}

Lịch sử Webhook

GET /api/v1/webhooks/history?per_page=20
Authorization: Bearer YOUR_API_KEY

Response

{
  "status": true,
  "messages": "Thành công",
  "history": [
    {
      "id": 35,
      "webhook_id": 1,
      "endpoint": "https://your-domain.com/webhook",
      "status_code": 200,
      "status": 1,
      "call_time": "2026-03-22 12:40:01",
      "bank": "ACB",
      "type": "IN",
      "account": "7465441",
      "transaction_id": "42896",
      "description": "DH001234 Thanh toan don hang",
      "amount": 220000,
      "date": "2026-03-22 15:34:12"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 35,
    "last_page": 2
  }
}

Mô tả trường

Trường	Kiểu	Mô tả
id	integer	ID log
webhook_id	integer	ID webhook
endpoint	string	URL đã gọi
status_code	integer	HTTP status code từ server bạn
status	integer	`1` = thành công, `0` = lỗi
call_time	string	Thời gian gọi
bank	string	Mã ngân hàng
type	string	IN/OUT
account	string	Số tài khoản
transaction_id	string	Mã giao dịch
description	string	Nội dung
amount	integer	Số tiền (VND)
date	string	Thời gian giao dịch

Gửi lại Webhook

POST /api/v1/webhooks/{history_id}/resend
Authorization: Bearer YOUR_API_KEY

Gửi lại payload của giao dịch đã thất bại.

Response

{
  "status": true,
  "messages": "Đã gửi lại webhook"
}