> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eholdings.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Thiết lập webhook

> Bật tính năng, thêm địa chỉ nhận, đổi khoá bí mật.

Webhook cho phép hệ thống của cửa hàng nhận sự kiện (tiền vào, tài khoản nhận tiền sẵn sàng…) ngay khi chúng xảy ra, thay vì phải hỏi lại liên tục. Mỗi sự kiện được gửi bằng một yêu cầu HTTPS `POST` tới địa chỉ cửa hàng đăng ký, kèm chữ ký theo chuẩn [Standard Webhooks](https://www.standardwebhooks.com/) để hệ thống của bạn kiểm tra tin đúng là do chúng tôi gửi.

## Bật tính năng và phân quyền

* Tính năng **Webhook** không bật sẵn. Liên hệ bộ phận hỗ trợ để bật cho cửa hàng. Cửa hàng chưa được bật thì mục Webhook không hiện, kể cả với chủ cửa hàng.
* Quyền **Webhook (Xem)** cho xem địa chỉ nhận và nhật ký gửi. Quyền **Webhook (Quản lý)** cho thêm, sửa, xoá địa chỉ, đổi khoá bí mật, gửi thử và gửi lại tin.
* Webhook nhận toàn bộ nội dung của sự kiện, trong đó có nội dung chuyển khoản do người chuyển nhập. Vì vậy bạn chỉ chọn được những sự kiện mà **chính bạn** có quyền xem: sự kiện về giao dịch và tài khoản nhận tiền (`payment.*`) cần quyền xem **Nhận tiền**. Quyền này được kiểm lại ở mọi thao tác ghi: thêm, sửa (kể cả chỉ đổi địa chỉ), đổi khoá, bật lại, gửi thử, gửi lại.

## Thêm một địa chỉ nhận

Vào **Nhà phát triển › Webhook › Thêm webhook**, nhập:

| Mục | Quy tắc |
| - | - |
| Địa chỉ nhận | Chỉ `https`. Cổng `443` (mặc định) hoặc `8443`. Không chứa tên đăng nhập hay mật khẩu (`https://user:pass@…`). Tối đa 2048 ký tự. Không trỏ vào mạng nội bộ (localhost, dải IP riêng). |
| Sự kiện nhận | Chọn một hay nhiều sự kiện, xem [Danh mục sự kiện](https://docs.eholdings.app/nha-phat-trien/webhook/danh-muc-su-kien.md). |
| Mô tả | Tuỳ chọn, tối đa 200 ký tự. |

Mỗi cửa hàng có tối đa **5** địa chỉ, tính cả địa chỉ đang tắt; xoá địa chỉ không còn dùng để thêm địa chỉ mới. Địa chỉ webhook thường chứa mã bí mật trong đường dẫn hoặc query; hệ thống chỉ ghi tên miền vào nhật ký hoạt động và log lỗi.

> [!WARNING]
>
> Sau khi tạo, hệ thống hiện **khoá bí mật** dạng `whsec_…` **một lần duy nhất**. Lưu ngay vào nơi an toàn (biến môi trường, kho bí mật). Chúng tôi chỉ giữ bản đã mã hoá và không xem lại được khoá; nếu mất, hãy đổi khoá như ở mục Đổi khoá bí mật bên dưới.

Cùng lúc đó, một tin thử `test.ping` được xếp hàng gửi tới địa chỉ mới. Kết quả hiện ở tab **Nhật ký gửi** và không chặn việc tạo.

Nút **Gửi thử** ở mỗi địa chỉ gửi thêm một tin `test.ping` bất cứ lúc nào: tối đa 3 tin thử đang chờ cùng lúc và 10 tin thử mỗi giờ cho mỗi địa chỉ, tính cả tin thử lúc tạo.

## Đổi khoá bí mật

**Đổi khoá bí mật** (menu của mỗi địa chỉ) tạo khoá mới, hiện một lần. Khoá cũ **vẫn dùng được 24 giờ**: trong thời gian đó mỗi tin mang cả hai chữ ký trong `webhook-signature`, cách nhau một dấu cách, và thư viện Standard Webhooks chấp nhận tin nếu một trong hai khớp. Hãy cập nhật khoá mới vào hệ thống của bạn trong 24 giờ. Đổi khoá lần nữa trong thời gian đó thì khoá cũ nhất hết hiệu lực.

Nên đổi khoá khi nghi khoá bị lộ, khi người giữ khoá nghỉ việc, hoặc định kỳ.

## Webhook tự động tắt

| Lý do hiện trên giao diện | Khi nào |
| - | - |
| Máy chủ trả về 410 | Bạn trả `410` cho một lượt gửi: tắt ngay. |
| Không nhận được tin nào trong 5 ngày | Mọi lượt gửi tới địa chỉ đều thất bại trong 5 ngày liên tục. |

Webhook do hệ thống tự tắt hiện một thông báo ở đầu danh sách, gọi bằng mô tả và địa chỉ, kèm lý do và nút **Bật lại**. Webhook bạn tự tắt (mục **Tắt** ở menu ••• của dòng) ghi "Đã tắt" ở cột Trạng thái, và bạn bật lại ở chính menu đó.

Mỗi tin chỉ được thử trong khoảng 3 ngày, nên chỉ webhook **vẫn tiếp tục nhận sự kiện mới** mới chạm mốc 5 ngày. Một webhook lỗi một lần rồi không có sự kiện nào nữa thì vẫn giữ nguyên bật.

Khi webhook tắt (do bạn hay do hệ thống), sự kiện xảy ra trong lúc đó **được giữ 72 giờ** ở trạng thái **Tạm giữ**. **Bật lại** trong 72 giờ thì chúng được gửi bù; quá 72 giờ thì bị huỷ. Bật lại cũng xoá dấu "đang lỗi liên tục" của địa chỉ. Hãy sửa lỗi ở hệ thống của bạn trước khi bật lại.

Khi hệ thống tự tắt một webhook, chủ cửa hàng nhận email báo kèm thời hạn giữ sự kiện, nếu tài khoản của chủ cửa hàng có email.

Bộ phận hỗ trợ có thể bật lại giúp một webhook do **hệ thống** tự tắt, không bật lại webhook bạn tự tắt. Việc này hiện trong nhật ký hoạt động của cửa hàng là "Bộ phận hỗ trợ bật lại webhook".

## Địa chỉ IP gửi đi

Nếu hệ thống của bạn chỉ nhận kết nối từ một số địa chỉ IP, hãy xin danh sách IP gửi đi từ bộ phận hỗ trợ. Địa chỉ IP có thể đổi khi hạ tầng đổi và sẽ được báo trước. Đừng chỉ dựa vào IP để xác thực; luôn kiểm tra chữ ký như ở trang [Nhận và xử lý tin](https://docs.eholdings.app/nha-phat-trien/webhook/nhan-va-xu-ly-tin.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.