# Webhook (/vi/webhooks)



Webhook thông báo cho server của bạn về các thay đổi trong tổ chức Tapaya. Sử dụng cùng một tích hợp cho thanh toán tại cửa hàng và thanh toán trực tuyến, bất kể đơn vị xử lý thanh toán.

## Cách hoạt động [#how-it-works]

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Server của bạn" label="Một thay đổi được xác nhận sẽ đưa sự kiện vào hàng đợi. Tapaya ký và gửi sự kiện. Bên nhận xác thực rồi lưu sự kiện. Phản hồi 2xx xác nhận việc gửi thành công; khi thất bại, hệ thống thử lại từ bước gửi, tối đa 12 lần rồi dừng." event="Thay đổi đã lưu" queue="Sự kiện trong hàng đợi" send="POST có chữ ký" receive="Xác thực và lưu" delivered="Đã gửi thành công" />

Cấu hình một địa chỉ đích HTTPS cho mỗi tổ chức và chọn các sự kiện bạn cần. Tapaya gửi yêu cầu HTTP `POST` kèm bản lưu (snapshot) JSON và chữ ký. Xác thực chữ ký, lưu sự kiện và trả về phản hồi thành công trước khi xử lý logic nghiệp vụ.

Bạn có thể đăng ký từng loại hoặc tất cả các loại được hỗ trợ. Đăng ký tất cả các loại cũng nhận những loại mới được hỗ trợ trong tương lai, vì vậy hãy bỏ qua các loại mà ứng dụng của bạn không nhận diện được.

## Tích hợp nhanh [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Lưu địa chỉ đích [#save-a-destination]

  Trong Platform, mở **API Keys**, rồi **Webhooks**. Nhập URL HTTPS của bạn, chọn các sự kiện bạn cần và lưu. Sao chép signing secret (khóa ký) ngay lúc này; khóa chỉ hiển thị một lần. Xem [Cấu hình](/webhooks/configuration).

  ### Xác thực từng yêu cầu [#verify-each-request]

  Tính HMAC-SHA256 trên dấu thời gian, một dấu chấm và nội dung gốc bằng signing secret của bạn, rồi so sánh kết quả với `X-Tapaya-Signature`. Xem [Kiểm tra chữ ký](/webhooks/receiving#check-the-signature).

  ### Lưu sự kiện, rồi trả về 2xx [#store-the-event-then-return-2xx]

  Lưu sự kiện với `id` duy nhất, trả lời `2xx` trong vòng 10 giây và xử lý sự kiện sau đó. Xem [Lưu và xác nhận](/webhooks/receiving#store-and-acknowledge).

  ### Gửi webhook kiểm tra [#send-a-test-webhook]

  Trên cùng trang đó, dùng thao tác kiểm tra để gửi một `webhook.test` có chữ ký. Xem [Gửi webhook kiểm tra](/webhooks/receiving#send-a-test-webhook).
</div>

## Cấu trúc chung của sự kiện [#event-envelope]

Mỗi sự kiện sử dụng cấu trúc chung này. Bản lưu của tài nguyên trong `data` phụ thuộc vào loại sự kiện.

```json
{
  "id": "019a0000-0000-7000-8000-000000000001",
  "type": "payment.succeeded",
  "apiVersion": "1",
  "organizationId": "019a0000-0000-7000-8000-000000000002",
  "merchantId": "019a0000-0000-7000-8000-000000000005",
  "createdAt": "2026-10-30T12:00:00.000000Z",
  "data": {
    "payment": {
      "id": "019a0000-0000-7000-8000-000000000003",
      "token": "example_payment_token",
      "merchantId": "019a0000-0000-7000-8000-000000000005",
      "status": "success",
      "statusId": 2,
      "requestedAmount": 10000,
      "requestedCurrencyId": 203,
      "settlementAmount": 10000,
      "settlementCurrencyId": 203
    }
  }
}
```

| Trường           | Ý nghĩa                                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | ID duy nhất của sự kiện. Dùng ID này để loại bỏ các lần gửi trùng lặp. Các lần thử lại giữ nguyên ID.                                       |
| `type`           | Tên sự kiện trong [danh mục sự kiện](/webhooks/events).                                                                                     |
| `apiVersion`     | Mã định danh cấu trúc payload, hiện là chuỗi `"1"`.                                                                                         |
| `organizationId` | Tổ chức sở hữu sự kiện. Kiểm tra xem tổ chức có khớp với tích hợp của bạn không.                                                            |
| `merchantId`     | Merchant sở hữu tài nguyên. Có thể là `null` đối với các khoản thanh toán cũ chưa xác định được chủ sở hữu hoặc một lần kiểm tra chẩn đoán. |
| `createdAt`      | Thời gian UTC khi sự kiện được ghi nhận, thay vì thời gian gửi.                                                                             |
| `data`           | Bản lưu bất biến của tài nguyên tại thời điểm ghi nhận sự kiện.                                                                             |

Số tiền là số nguyên theo đơn vị nhỏ nhất của loại tiền tệ tương ứng với trường. Ví dụ, `10000` với ID tiền tệ dạng số ISO 4217 `203` có nghĩa là 100,00 CZK. Số tiền yêu cầu và số tiền quyết toán có thể sử dụng các loại tiền tệ khác nhau.

Mỗi loại sự kiện đặt bản lưu riêng của mình bên trong `data`. Xem [Loại sự kiện](/webhooks/events) để biết mọi dạng payload và giá trị trạng thái.

## Quy tắc gửi [#delivery-rules]

Tapaya gửi sự kiện ngay khi thay đổi của sự kiện được lưu, và tiếp tục gửi cho đến khi server của bạn trả lời `2xx`.

| Quy tắc   | Cách hoạt động                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------ |
| Xác nhận  | Mọi phản hồi `2xx` trong vòng 10 giây. Hệ thống không đi theo chuyển hướng.                                        |
| Thử lại   | Tối đa 12 lần thử trong khoảng 20 giờ, với khoảng chờ 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 và 360 phút.           |
| Thứ tự    | Không được đảm bảo. Sự kiện được gửi ít nhất một lần, vì vậy hãy dự liệu các sự kiện trùng lặp và bản lưu cũ hơn.  |
| Đồng thời | 2 yêu cầu cùng lúc cho mỗi tổ chức, dùng chung với các lần kiểm tra thủ công. Các sự kiện khác chờ trong hàng đợi. |

Một lần gửi thất bại không bao giờ làm thay đổi chính khoản thanh toán, và các lần gửi trước đây không thể gửi lại. Để cập nhật sau sự cố gián đoạn, hãy đọc trạng thái hiện tại qua [API thanh toán và merchant](/platform-api/reporting).

## Bắt đầu tích hợp [#start-integrating]

<Cards>
  <Card title="Cấu hình địa chỉ đích" href="/webhooks/configuration">
    Đặt URL, chọn sự kiện và lưu signing secret (khóa ký).
  </Card>

  <Card title="Duyệt các loại sự kiện" href="/webhooks/events">
    Tìm điều kiện kích hoạt chính xác cho từng sự kiện thanh toán, merchant và onboarding.
  </Card>

  <Card title="Xác thực và kiểm tra" href="/webhooks/receiving">
    Xác thực chữ ký và gửi webhook chẩn đoán.
  </Card>
</Cards>