Webhook 事件

平台主動送出的事件，以下列出每個事件 payload 的欄位。外層信封、簽章驗證與重試規則請見「接收 Webhook」。

submission.created

提交已被接受，批閱已排入佇列。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

第一段說的是這個事件掛在哪個資源上（序號的範圍、後續查詢的對象），不一定是事件所描述的物件：response.evaluation_revised 掛在作答上，但被修訂的是它的批閱結果。真正的主體在第二段，格式為 {主體}_{發生了什麼}：grading_started、grading_completed、 grading_failed、evaluation_revised。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

它計算的是該資源所有發出的事件，與訂閱過濾無關；所以只訂閱部分事件時，看到序號有缺口是正常的。遞送是至少一次且各自重試，到達順序沒有保證：用 sequence 重建每個資源的順序，遇到缺口不要空等，直接重新查詢資源並從現況繼續。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

覆核事件掛在作答上而不是批閱結果上：每一個覆核版本都是全新的 eval_ 紀錄，若以它為範圍，序號會永遠是 1、完全不帶資訊，而稽核正是最需要順序的地方。掛在作答上，一筆作答的完整歷程就是單一遞增序列（grading_started → grading_completed → evaluation_revised → …）。被修訂的批閱結果版本仍由 payload 的 evaluation_id 指明。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/submission.created

submission.completed

每一筆作答都已到達終態（completed 或 failed）。這是提交的終態事件。

沒有部分完成的事件。 若要知道是否有個別作答失敗，請查看 summary.failed； failed 非零時仍然送出 submission.completed。

重新排程過的作答再次完成時，這個事件會再送一次，並附上重算後的 summary。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/submission.completed

submission.failed

提交整體失敗且無法再到達 completed。

個別作答失敗不會造成提交失敗，該情形會出現在 submission.completed 的 summary.failed 以及 response.grading_failed 事件裡。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/submission.failed

response.grading_started

單一作答開始批閱。

屬於選擇性訂閱：每筆作答都會產生一組 started/completed，量很大。只有需要即時顯示逐題進度時才訂閱。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/response.grading_started

response.grading_completed

單一作答完成批閱，產生了一筆批閱結果。

內部批閱信心值不會出現在這個 payload（或客戶合約的任何地方）；取而代之的是 review_suggested 這個布林提示。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/response.grading_completed

response.grading_failed

單一作答批閱失敗。該作答的狀態是 failed，但父提交仍然可以完成。復原方式是在 Studio 中重新排程，而非覆核；失敗的作答沒有可供覆核的批閱結果。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/response.grading_failed

response.evaluation_revised

一次人工覆核在某筆作答上產生了新的批閱結果版本。初次批閱（version 1）由 response.grading_completed 通知，不會觸發這個事件。

一次覆核只送出一個事件。 沒有另外的「分數改變了」事件：previous_score 一定會帶，只在意分數有沒有動的消費端拿它與 score 相比即可。拆成兩個事件會讓同一次狀態變更產生兩個不同的 event_id，而以 event_id 去重是攔不住那種重複的。

屬於選擇性稽核訂閱，在需要同步分數歷史或對分數異動發出告警時使用。它的流量遠低於同一家族的 response.grading_*，因此建議直接以完整名稱訂閱，而不是用 response.*。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

event_id?string

全域唯一的事件識別碼，evt_ 前綴。同一事件的每次重試都相同，是主要的去重鍵。

event_type?string

事件名稱，一律為 {resource}.{event} 兩段，第一段恆等於 resource_type。

sequence?number

以資源為單位的計數器，從 1 開始，該資源每有一個事件就加一。

resource_id?string

這個事件所掛靠的資源 id（sub_ / resp_），序號以它為範圍。

resource_type?string

恆等於 event_type 的第一段。

Value in

"submission"
"response"

idempotency_key?string

同一事件重試時保持不變，可作為 event_id 之外的等效去重鍵。當成不透明字串處理。

occurred_at?string

狀態變化發生的時間，發出時就固定，每次重試都相同。

Formatdate-time

delivered_at?string

這一次遞送嘗試發出的時間，每次重試都會重新產生。

這也是為什麼絕對不要用內容雜湊去重：重試的內容不是逐位元組相同的。

Formatdate-time

payload?

回應內容

請求範例

POST/response.evaluation_revised

200

200

200

200

200

200

200