# Cấu hình (/vi/webhooks/configuration)





Mỗi tổ chức có một địa chỉ đích webhook và một signing secret (khóa ký) đang hoạt động. Cấu hình trong Platform hoặc từ server của bạn.

| Thông tin           | Giá trị                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------- |
| Base URL            | `https://api.sandbox.tapaya.com` cho sandbox, `https://api.tapaya.com` cho production    |
| Xác thực            | Server Secret Token trong `Authorization`. Xem [Xác thực](/platform-api#authentication). |
| Phạm vi             | Một địa chỉ đích cho mỗi tổ chức                                                         |
| Hướng dẫn liên quan | [Xác thực và kiểm tra](/webhooks/receiving)                                              |

## Cấu hình trong Platform [#configure-in-the-platform]

Mở [API Keys](https://platform.tapaya.com/api-keys/) của tổ chức bạn và tìm **Webhooks**.

1. Nhập URL HTTPS công khai của bạn.
2. Chọn các sự kiện bạn cần, hoặc bật **Subscribe to all webhook types**.
3. Bật **Enable** và nhấp **Save**.
4. Sao chép signing secret và lưu trên server của bạn.
5. Gửi một [webhook kiểm tra](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Signing secret chỉ hiển thị một lần">
  Sao chép giá trị này khi bạn tạo hoặc xoay vòng địa chỉ đích; bạn không thể lấy lại sau đó. Giá trị này chỉ dùng để xác thực các webhook đến. Server Secret Token của bạn cấp quyền cho các yêu cầu cấu hình.
</Callout>

## Tất cả thao tác [#all-operations]

| Thao tác                                  | Dùng để                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| [Lưu địa chỉ đích](#save-a-destination)   | Tạo hoặc thay thế đăng ký hiện tại, hoặc xoay vòng signing secret của đăng ký. |
| [Đọc địa chỉ đích](#read-a-destination)   | Lấy URL hiện tại, chế độ đăng ký và trạng thái bật.                            |
| [Xóa địa chỉ đích](#delete-a-destination) | Xóa đăng ký cùng hàng đợi và lịch sử gửi.                                      |

## Quản lý địa chỉ đích [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Lưu địa chỉ đích" id="save-a-destination">
    **Dùng để** kết nối bên nhận HTTPS và chọn các sự kiện cần gửi.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Cần biết:**

    * Thao tác này thay thế cấu hình đã lưu; không thêm endpoint thứ hai.
    * Việc tạo mới và xoay vòng theo yêu cầu rõ ràng trả về `{"signingSecret":"twhsec_..."}`. Cập nhật thông thường trả về `{"signingSecret":null}`.
    * Lưu toàn bộ giá trị bí mật được trả về, bao gồm tiền tố. GET không bao giờ trả về giá trị này.
    * Token của bạn quyết định tổ chức; không gửi ID tổ chức.

    **Tham số:**

    | Trường                   | Bắt buộc | Ý nghĩa                                                                                                           |
    | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Có       | URL HTTPS công khai trên cổng 443, tối đa 2,048 ký tự, không có thông tin đăng nhập nhúng hoặc phần fragment.     |
    | `eventTypes`             | Có       | Mảng tên từ [danh mục](/webhooks/events). Chọn ít nhất một tên trừ khi đăng ký tất cả các loại.                   |
    | `subscribeAllEventTypes` | Không    | Mặc định là `false`. Đặt `true` với `eventTypes: []` để bao gồm mọi loại được hỗ trợ hiện tại và trong tương lai. |
    | `enabled`                | Có       | Khi là `true`, ghi nhận các sự kiện mới phù hợp và gửi các sự kiện trong hàng đợi.                                |
    | `rotateSecret`           | Có       | Khi là `true`, tạo và trả về signing secret mới.                                                                  |
  </Accordion>

  <Accordion title="Đọc địa chỉ đích" id="read-a-destination">
    **Dùng để** xem đăng ký đã lưu mà không tiết lộ signing secret.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Cần biết:**

    * GET trả về `404` khi tổ chức này không có địa chỉ đích.
    * Đăng ký tất cả các loại trả về mảng `eventTypes` rỗng với `subscribeAllEventTypes: true`.
    * Phản hồi không bao giờ bao gồm signing secret.
    * Dùng `availableEventTypes` để xây dựng bộ chọn sự kiện mà không phải mã hóa cứng danh mục.

    **Trả về:**

    | Trường                   | Ý nghĩa                                                                      |
    | ------------------------ | ---------------------------------------------------------------------------- |
    | `url`                    | Địa chỉ đích HTTPS đã lưu.                                                   |
    | `eventTypes`             | Các đăng ký cụ thể hoặc mảng rỗng ở chế độ tất cả các loại.                  |
    | `subscribeAllEventTypes` | Cho biết có chọn các loại được hỗ trợ hiện tại và trong tương lai hay không. |
    | `enabled`                | Cho biết webhook có được bật hay không.                                      |
    | `availableEventTypes`    | Mọi tên sự kiện bạn có thể đăng ký.                                          |
  </Accordion>

  <Accordion title="Xóa địa chỉ đích" id="delete-a-destination">
    **Dùng để** ngắt kết nối tổ chức và xóa các lần gửi trong hàng đợi cùng lịch sử gửi.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Cần biết:**

    * Khi thành công, trả về HTTP `204` không có nội dung phản hồi.
    * Yêu cầu đang được gửi vẫn có thể đến sau khi xóa.
    * Tạo lại địa chỉ đích sẽ tạo signing secret mới và không khôi phục các sự kiện đã xóa.
  </Accordion>
</Accordions>

## Quy tắc địa chỉ đích [#configuration]

### Thay đổi thiết lập [#configuration-changes]

| Khi bạn                                   | Điều gì xảy ra                                                                                                                                                                                |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Thay đổi URL, sự kiện hoặc signing secret | Sự kiện mới dùng thiết lập mới. Các sự kiện trong hàng đợi giữ URL và signing secret cũ, vì vậy hãy giữ cả hai hoạt động cho đến khi hàng đợi được xử lý hết.                                 |
| Tắt webhook                               | Các lần gửi trong hàng đợi tạm dừng và không ghi nhận sự kiện mới. Bật lại sẽ tiếp tục xử lý hàng đợi, nhưng các thay đổi bị bỏ lỡ không được bổ sung hồi tố. Webhook kiểm tra vẫn hoạt động. |
| Xóa địa chỉ đích                          | Các sự kiện trong hàng đợi và lịch sử gửi bị xóa. Yêu cầu đang được gửi vẫn có thể đến. Tạo lại địa chỉ đích sẽ tạo signing secret mới.                                                       |

### Yêu cầu đối với URL [#destination-requirements]

* HTTPS công khai trên cổng 443. Localhost và mạng riêng bị từ chối, và DNS được kiểm tra lại ở mỗi lần kết nối.
* Không có thông tin đăng nhập nhúng, không có phần fragment và không đi theo chuyển hướng.
* Không có header cấp quyền tùy chỉnh. Thay vào đó, hãy xác thực chữ ký Tapaya, hoặc đặt một bộ chuyển tiếp phía server ở trước URL yêu cầu khóa riêng.

## Lỗi [#errors]

Các yêu cầu cấu hình thất bại với những phản hồi sau. Bên nhận từ chối hoặc bỏ lỡ một lần gửi là một vấn đề khác; xem [Xử lý lỗi](/webhooks/receiving#handle-errors).

| Phản hồi      | Ý nghĩa                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400` khi PUT | URL không hợp lệ, loại sự kiện không được hỗ trợ, thiếu trường bắt buộc hoặc danh sách chọn sự kiện cụ thể rỗng. |
| `401`         | Server Secret Token bị thiếu hoặc không hợp lệ.                                                                  |
| `404` khi GET | Tổ chức sở hữu Server Secret Token chưa có địa chỉ đích.                                                         |

Tiếp tục với [xác thực chữ ký và gửi kiểm tra](/webhooks/receiving).