> For the complete documentation index, see [llms.txt](https://docs.loomgate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loomgate.io/webhooks/webhook-endpoints.md).

# Thiết lập webhook

Tạo webhook endpoint, yêu cầu về URL, cơ chế gửi lại và cách xử lý đúng.

## Tạo endpoint

Trong dashboard merchant, mục [**Webhook**](https://app.loomgate.io/webhooks), thêm endpoint:

* **URL nhận webhook**: ví dụ `https://shop.example.com/webhooks/loomgate`.
* **Sự kiện**: chọn các loại muốn nhận; không chọn loại nào = nhận tất cả.

Sau khi tạo, sao chép **ID endpoint** (`we_…`): bạn cần nó để xác minh chữ ký. Mỗi tài khoản có tối đa 16 endpoint; endpoint có thể sửa, tắt hoặc xóa. Endpoint bị tắt không nhận sự kiện mới.

## Yêu cầu về URL

* Phải là `https://` trên cổng mặc định (443), với **tên miền** công khai: không dùng địa chỉ IP, cổng khác (ví dụ `:8443`), hay tên chỉ có trong mạng nội bộ (`localhost`, `*.local`, `*.internal`…). Tối đa 2048 ký tự.
* Trả về mã `2xx` trong vòng **10 giây**. Mọi mã khác, lỗi kết nối hay quá thời gian đều tính là thất bại.
* Chuyển hướng (3xx) **không được theo**: dùng đúng URL cuối cùng.
* Route này phải cho phép request không đăng nhập (xác thực bằng chữ ký). Nếu dùng tường lửa ứng dụng hay plugin bảo mật, hãy mở route này.

## Webhook được gửi từ đâu

Webhook đi ra từ mạng của Loomgate, qua các địa chỉ IP dùng chung, thay đổi theo thời gian và không có danh sách cố định. **Đừng chặn hay chỉ cho phép theo địa chỉ IP**: hãy cho route webhook nhận request từ mọi địa chỉ và xác thực từng webhook bằng [chữ ký](/webhooks/verify-signatures.md).

## Một lần gửi trông như thế nào

```http
POST /webhooks/loomgate HTTP/1.1
Content-Type: application/json
User-Agent: Loomgate-Webhooks/1.0
Loomgate-Event-Id: evt_9fK2mQ7xR4tL1vB8nC3d
Loomgate-Event-Type: payment_intent.succeeded
Loomgate-Signature: t=1790000000,kid=k1,v1=/lvIiLtH/ndQufwkco75zmDQjuagCiDFztEbB1NLT8RateCw…

{"id":"evt_9fK2mQ7xR4tL1vB8nC3d","object":"event","type":"payment_intent.succeeded","created":1790000000,"data":{"object":{…}}}
```

`Loomgate-Event-Id` và `Loomgate-Event-Type` chỉ để tiện đọc, không được ký: luôn lấy thông tin từ body sau khi đã [xác minh chữ ký](/webhooks/verify-signatures.md).

## Gửi lại khi thất bại

Lần gửi đầu đi ngay khi có sự kiện (trễ vài giây). Nếu thất bại, Loomgate gửi lại sau:

| Sau lần thử | Chờ     |
| ----------- | ------- |
| 1           | 30 giây |
| 2           | 2 phút  |
| 3           | 10 phút |
| 4           | 1 giờ   |
| 5           | 4 giờ   |
| 6           | 12 giờ  |
| 7           | 24 giờ  |

Sau 8 lần thất bại, lần gửi đó được đánh dấu `failed`. Xem lịch sử gửi (trạng thái, mã HTTP, lỗi) ở mục **Webhook** của dashboard.

## Xử lý webhook đúng cách

* **Xác minh chữ ký trước** mọi việc khác, trên body gốc chưa qua xử lý.
* **Trả 2xx nhanh**: ghi nhận sự kiện rồi xử lý nặng (gửi email, gọi hệ thống kho…) phía sau.
* **Chống xử lý trùng**: một sự kiện có thể tới hơn một lần. Lưu `id` của event (`evt_…`) và bỏ qua nếu đã xử lý.
* **Đừng dựa vào thứ tự**: các sự kiện có thể tới không theo thứ tự xảy ra. Khi cần trạng thái mới nhất, đọc lại đối tượng bằng API (ví dụ `GET /partner/v1/payment_intents/{id}`).
* **Đối soát định kỳ**: nếu máy chủ của bạn ngừng lâu hơn thời gian gửi lại, dùng `GET /partner/v1/payment_intents` để tìm các payment đã thành công mà bạn chưa ghi nhận.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.loomgate.io/webhooks/webhook-endpoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.