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

# Danh mục event

> Mỗi event webhook gửi khi nào, không gửi khi nào, và thứ tự của chúng trong một quy trình ký

Có 8 event, chia 3 nhóm. Subscription chỉ nhận những event đã được chọn khi quản trị viên tạo nó.

| Nhóm | Mục đích | Mặc định |
| - | - | - |
| document | Đồng bộ trạng thái cuối của hồ sơ, lấy file | Bật sẵn |
| notification | Biết từng bước của quy trình để tự gửi thông báo | Phải đăng ký mới nhận |
| test | Kiểm tra endpoint | Gửi khi quản trị viên bấm Test |

***

## Bảng event

| Event | Gửi khi | Không gửi khi |
| - | - | - |
| `document.completed` | Bước cuối cùng được duyệt, hồ sơ hoàn tất | — |
| `document.rejected` | Một bước bị từ chối, quy trình dừng | — |
| `notification.task_assigned_internal` | Một bước được giao cho nhân sự nội bộ (người, vai trò hoặc nhóm); gửi lại lời mời | Bước giao cho người ký bên ngoài; bước không có ai có email |
| `notification.task_assigned_external` | Một bước được giao cho người ký bên ngoài (email, số điện thoại hoặc đối tác); gửi lại lời mời | Bước giao nội bộ |
| `notification.task_completed` | Một bước được duyệt/ký **xong hẳn** | Bước bị từ chối; bước quá hạn; bước cần nhiều người mà còn người chưa ký; lúc khởi động quy trình |
| `notification.task_rejected` | Một bước bị từ chối | — |
| `notification.process_finished` | Bước cuối cùng được duyệt | — |
| `webhook.test` | Quản trị viên bấm Test, hoặc gọi API ping | — |

> [!NOTE]
>
> Bước cần nhiều người cùng ký chỉ gửi `notification.task_completed` **một lần**, sau khi người cuối cùng ký. Từng người trong bước đó vẫn có mặt trong `relatedParties.actors`.

### Email tương ứng của econtractid

Bốn event `notification.*` đi kèm một email do econtractid gửi; bật [uỷ quyền gửi email](https://docs.econtractid.com/api-reference/webhook.md#uỷ-quyền-gửi-email) để bạn tự gửi thay.

| Event | Email econtractid gửi |
| - | - |
| `notification.task_assigned_internal` | Thư giao việc nội bộ |
| `notification.task_assigned_external` | Thư mời ký (kèm tài khoản nếu có) |
| `notification.task_rejected` | Thư báo từ chối |
| `notification.process_finished` | Thư báo hoàn tất |
| `notification.task_completed` | **Không có** — chỉ có ở webhook |

***

## Thứ tự trong một quy trình

Ví dụ quy trình 3 bước: trưởng phòng duyệt → khách hàng ký → giám đốc ký.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant P as Quy trình ký
    participant Y as Webhook của bạn

    Note over P: Tạo hồ sơ, khởi động quy trình
    P->>Y: notification.task_assigned_internal (bước 1)
    Note over P: Trưởng phòng duyệt
    P->>Y: notification.task_completed (bước 1)
    P->>Y: notification.task_assigned_external (bước 2)
    Note over P: Khách hàng ký
    P->>Y: notification.task_completed (bước 2)
    P->>Y: notification.task_assigned_internal (bước 3)
    Note over P: Giám đốc ký
    P->>Y: notification.task_completed (bước 3, nextStep = null)
    P->>Y: notification.process_finished
    P->>Y: document.completed
```

Khi một bước bị từ chối, quy trình dừng tại đó:

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant P as Quy trình ký
    participant Y as Webhook của bạn

    P->>Y: notification.task_assigned_external (bước 2)
    Note over P: Khách hàng từ chối
    P->>Y: notification.task_rejected (bước 2)
    P->>Y: document.rejected
    Note over Y: Không có task_completed cho bước 2
```

> [!WARNING]
>
> Các event phát sinh từ cùng một thao tác (ví dụ `task_completed` của bước 1 và `task_assigned_*` của bước 2) được gửi độc lập, **không đảm bảo thứ tự đến**. Đừng suy luận trạng thái từ thứ tự nhận; dùng `data.step.order`, `data.nextStep` và `createdAt`.

***

## Muốn báo cho ai thì dùng gì

Khi đã tắt email của econtractid và tự gửi thông báo, lấy người nhận như sau:

| Bạn muốn báo | Event | Lấy người nhận ở |
| - | - | - |
| Người được giao bước tiếp theo | `task_assigned_internal` / `task_assigned_external` | `data.recipients[]` |
| Người tạo hồ sơ: "bước X đã xong" | `task_completed` | `data.relatedParties.creator` |
| Những người đã xử lý trước đó: "bước X đã xong" | `task_completed` | `data.relatedParties.actors[]` (hoặc `data.recipients[]` — đã gộp sẵn người tạo + người xử lý trước, bỏ trùng, trừ người vừa xử lý) |
| Mọi người liên quan: "hồ sơ bị từ chối" | `task_rejected` | `data.relatedParties.creator` + `data.relatedParties.actors[]` |
| Mọi người liên quan: "hồ sơ đã hoàn tất" | `process_finished` | `data.relatedParties.creator` + `data.relatedParties.actors[]` |

`relatedParties` có trong **mọi** event `notification.*` và `document.*`, cấu trúc giống nhau — xem [Payload tham chiếu](https://docs.econtractid.com/api-reference/webhook-payload.md#relatedparties).

***

## Hai cách cấu hình nhận webhook

| | Subscription | Cấu hình webhook cấp tổ chức (cũ) |
| - | - | - |
| Số URL | Nhiều, mỗi URL chọn event riêng | Một URL |
| Nhận `document.*` | Có | Có — chỉ khi tổ chức **không** có subscription nào đang bật cho event đó |
| Nhận `notification.*` | Có | Không |
| Secret | Riêng từng subscription | Một secret chung |

Tích hợp mới nên dùng subscription.

***

> [card] [Payload tham chiếu](https://docs.econtractid.com/api-reference/webhook-payload.md)
>
> Từng trường và ví dụ JSON cho mỗi event.

> [card] [Tổng quan & bảo mật](https://docs.econtractid.com/api-reference/webhook.md)
>
> Chữ ký HMAC, kiểm thử, retry.


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