# Tạo webhook

`POST https://api.pay2s.vn/api/v1/oauth/webhooks`

## Xác thực

Bearer. Scope cần có: `webhooks:write`. Gửi header `Authorization: Bearer ACCESS_TOKEN`.

## Tham số

Định dạng: **application/json**.

| Trường | Kiểu nhập | Yêu cầu |
|---|---|---|
| `bank_id` | string | Bắt buộc |
| `url` | string | Bắt buộc |
| `direction` | string | Bắt buộc |
| `request_key` | string | Bắt buộc |

Body JSON. bank_id phải được cấp quyền. url là địa chỉ HTTPS nhận giao dịch do dev truyền khi tạo webhook. App cũ có danh sách URL cố định vẫn phải dùng đúng địa chỉ đã cấu hình. direction: IN, OUT, ALL. request_key dài 8–80 ký tự chữ/số/._:-. Cùng key và payload trả cùng ID với replayed=true, không trả lại secret; khác payload trả 409. Lần đầu HTTP 201. Lưu signing_secret ngay; mất secret thì xóa và tạo lại với key mới.

Cần gói Pay2S còn hoạt động. Dữ liệu chỉ thuộc tài khoản/ngân hàng được cấp quyền; tài khoản demo chỉ đọc ngân hàng và giao dịch demo.

## Cách thử

Mở Playground bằng nút đầu trang, nhập thông tin của ứng dụng hoặc Access Token đã được cấp. [Hướng dẫn toàn bộ luồng](/docs/oauth/quickstart/). Code mẫu cURL, Node.js và PHP nằm dưới form Playground.

## Lỗi cần xử lý

`invalid_token` (401), `insufficient_scope` hoặc `active_plan_required` (403), dữ liệu không hợp lệ (422). Xem [bảng lỗi](/docs/oauth/errors/).


## Request và response tham khảo

Các mẫu dưới đây giữ cấu trúc trường và kiểu dữ liệu. Khóa, chữ ký, URL phiên đã được thay bằng placeholder; danh sách chỉ giữ tối đa hai phần tử và dữ liệu ảnh/PDF/XML dài được rút gọn. Không sao chép placeholder để gọi API thật.

### OAuth · Tạo webhook

<div class="doc-api-actions" data-doc-api-actions><a class="try-button" data-doc-playground href="/playground/?api=oauth-webhooks-create">Thử API trong Playground ↗</a><a class="try-button experience-button" data-doc-experience hidden>Trải nghiệm ↗</a></div>

**Đối chiếu mã nguồn backend; giá trị minh họa.** Body JSON. bank_id phải được cấp quyền. url là địa chỉ HTTPS nhận giao dịch do dev truyền khi tạo webhook. App cũ có danh sách URL cố định vẫn phải dùng đúng địa chỉ đã cấu hình. direction: IN, OUT, ALL. request_key dài 8–80 ký tự chữ/số/._:-. Cùng key và payload trả cùng ID với replayed=true, không trả lại secret; khác payload trả 409. Lần đầu HTTP 201. Lưu signing_secret ngay; mất secret thì xóa và tạo lại với key mới.

`POST /api/v1/oauth/webhooks`

Body:

```json
{
  "bank_id": "",
  "url": "",
  "direction": "IN",
  "request_key": ""
}
```

HTTP 201. Response:

```json
{
  "id": "WEBHOOK_ID_64_HEX",
  "signing_secret": "SIGNING_SECRET",
  "replayed": false
}
```