ประเภท Event และ Payload

หน้านี้คือ Reference ครบถ้วนสำหรับทุก Webhook Event ที่ Ocriva สามารถส่งออกได้ แต่ละส่วนอธิบาย Event พร้อมรายการ Field ใน Object payload และตัวอย่าง JSON จริง

โครงสร้าง Payload มาตรฐาน

ทุก Webhook Delivery — ไม่ว่าจะเป็น Event ประเภทใด — มีโครงสร้างภายนอกที่เหมือนกัน:

{
  "eventType": "document.processed",
  "eventId": "evt_1743418800000_abc123",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    // ข้อมูลเฉพาะของแต่ละ Event
  }
}

Field	Type	คำอธิบาย
`eventType`	`string`	Event ที่ทำให้เกิด Webhook นี้ (เช่น `document.processed`)
`eventId`	`string`	Identifier เฉพาะสำหรับ Delivery ครั้งนี้
`timestamp`	`string`	Timestamp ISO 8601 UTC ของเวลาที่ Event เกิดขึ้น
`organizationId`	`string`	ID ขององค์กรที่เป็นเจ้าของ Resource
`projectId`	`string`	ID ของ Project ที่ Resource นั้นอยู่
`payload`	`object`	ข้อมูลเฉพาะของ Event (ดูแต่ละส่วนด้านล่าง)

NOTE

eventId ใช้รูปแบบ evt_{unixMs}_{random6chars} — ตัวอย่างเช่น evt_1743418800000_abc123 ส่วน Unix Timestamp แสดงเวลาที่ Event ถูกสร้าง ไม่ใช่เวลาที่ส่ง Delivery

TIP

ใช้ eventId เพื่อสร้าง Event Handler ที่เป็น Idempotent บันทึก Event ID ที่ประมวลผลแล้ว และข้ามการประมวลผลหากได้รับ ID เดิมซ้ำ ซึ่งปกป้องคุณจาก Delivery ซ้ำที่เกิดจาก Retry

Document Events

Document Events จะทำงานเมื่อไฟล์แต่ละชิ้นเคลื่อนผ่านขั้นตอนการประมวลผล

`document.uploaded`

ทำงานทันทีเมื่อไฟล์ถูก Upload ไปยัง Ocriva สำเร็จ ก่อนที่ AI จะเริ่มประมวลผล

Field ใน Payload:

Field	Type	คำอธิบาย
`id`	`string`	ID ของ Upload Record
`fileName`	`string`	ชื่อไฟล์ต้นฉบับ
`fileSize`	`number`	ขนาดไฟล์เป็น Bytes
`mimeType`	`string`	MIME Type (เช่น `application/pdf`)
`status`	`string`	เป็น `uploaded` เสมอในขั้นตอนนี้
`templateId`	`string`	ID ของ Template ที่กำหนดสำหรับประมวลผล
`uploadedBy`	`string`	User ID ที่เริ่มการ Upload
`createdAt`	`string`	Timestamp ISO 8601 UTC

ตัวอย่าง:

{
  "eventType": "document.uploaded",
  "eventId": "evt_1743418800000_upl001",
  "timestamp": "2026-03-31T11:59:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_upl_001",
    "fileName": "invoice_march.pdf",
    "fileSize": 204800,
    "mimeType": "application/pdf",
    "status": "uploaded",
    "templateId": "tmpl_invoice_v2",
    "uploadedBy": "user_wicha01",
    "createdAt": "2026-03-31T11:59:00.000Z"
  }
}

`document.processed`

ทำงานเมื่อเอกสารผ่านการประมวลผล AI สำเร็จ นี่คือ Event ที่ใช้บ่อยที่สุด เพราะมีข้อมูลที่ดึงออกมาซึ่งระบบ Downstream ของคุณต้องการ

Field ใน Payload:

Field	Type	คำอธิบาย
`id`	`string`	ID ของ Upload Record
`fileName`	`string`	ชื่อไฟล์ต้นฉบับ
`status`	`string`	เป็น `completed` เสมอ
`extractedData`	`object`	ข้อมูลที่มีโครงสร้างที่ AI ดึงออกมา
`confidence`	`number`	คะแนนความมั่นใจในการดึงข้อมูล (0–1)
`processingTime`	`number`	เวลาที่ใช้ประมวลผลเป็น Milliseconds
`processedAt`	`string`	Timestamp ISO 8601 UTC ของเวลาที่เสร็จสิ้น

ตัวอย่าง:

{
  "eventType": "document.processed",
  "eventId": "evt_1743418800000_prc002",
  "timestamp": "2026-03-31T12:00:03.241Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_upl_001",
    "fileName": "invoice_march.pdf",
    "status": "completed",
    "extractedData": {
      "invoiceNumber": "INV-2026-0331",
      "vendor": "Acme Supplies Co.",
      "vendorTaxId": "0105560012345",
      "customer": "Beta Corp Ltd.",
      "issueDate": "2026-03-31",
      "dueDate": "2026-04-30",
      "subtotal": 14400.00,
      "vatAmount": 1008.00,
      "totalAmount": 15408.00,
      "currency": "THB",
      "lineItems": [
        {
          "description": "Cloud Storage (มีนาคม)",
          "quantity": 12,
          "unitPrice": 1200.00,
          "amount": 14400.00
        }
      ]
    },
    "confidence": 0.97,
    "processingTime": 3241,
    "processedAt": "2026-03-31T12:00:03.241Z"
  }
}

`document.failed`

ทำงานเมื่อเอกสารไม่สามารถประมวลผลได้สำเร็จ ใช้ Event นี้เพื่อเรียกใช้ Error Handling การแจ้งเตือน หรือ Workflow การตรวจสอบด้วยมือ

Field ใน Payload:

Field	Type	คำอธิบาย
`id`	`string`	ID ของ Upload Record
`fileName`	`string`	ชื่อไฟล์ต้นฉบับ
`status`	`string`	เป็น `failed` เสมอ
`errorMessage`	`string`	คำอธิบายที่อ่านได้ว่าเกิดอะไรขึ้น
`processingTime`	`number`	เวลาที่ผ่านไปก่อนเกิด Failure เป็น Milliseconds

ตัวอย่าง:

{
  "eventType": "document.failed",
  "eventId": "evt_1743418900000_fail003",
  "timestamp": "2026-03-31T12:01:40.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "doc_upl_002",
    "fileName": "corrupted_scan.pdf",
    "status": "failed",
    "errorMessage": "Unable to extract text: document appears to be a scanned image with insufficient resolution (below 150 DPI).",
    "processingTime": 1820
  }
}

Batch Events

Batch Events ทำงานเมื่อกลุ่มเอกสารถูก Upload หรือประมวลผลเสร็จพร้อมกัน

`batch.uploaded`

ทำงานเมื่อการ Upload แบบ Batch เสร็จสมบูรณ์ — ไฟล์ทั้งหมดใน Batch ได้รับโดย Ocriva และอยู่ในคิวรอประมวลผล

Field ใน Payload:

Field	Type	คำอธิบาย
`batchId`	`string`	Identifier เฉพาะของ Batch
`name`	`string`	ชื่อ Batch ที่ระบุตอน Upload
`totalFiles`	`number`	จำนวนไฟล์ทั้งหมดใน Batch
`templateId`	`string`	Template ที่ใช้กับทุกไฟล์ใน Batch นี้
`uploadedBy`	`string`	User ID ที่เริ่มการ Upload แบบ Batch
`createdAt`	`string`	Timestamp ISO 8601 UTC
`uploadIds`	`string[]`	Array ของ Upload Record ID แต่ละชิ้น

ตัวอย่าง:

{
  "eventType": "batch.uploaded",
  "eventId": "evt_1743418800000_bat004",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "batchId": "batch_march_invoices",
    "name": "ใบแจ้งหนี้มีนาคม 2026",
    "totalFiles": 47,
    "templateId": "tmpl_invoice_v2",
    "uploadedBy": "user_wicha01",
    "createdAt": "2026-03-31T12:00:00.000Z",
    "uploadIds": [
      "doc_upl_101",
      "doc_upl_102",
      "doc_upl_103"
    ]
  }
}

`batch.completed`

ทำงานเมื่อทุกไฟล์ใน Batch ประมวลผลเสร็จสิ้น (ทั้งสำเร็จและล้มเหลว) ใช้ Event นี้เพื่อเรียกใช้การรายงานระดับ Batch หรือการรวมข้อมูล

Field ใน Payload:

Field	Type	คำอธิบาย
`batchId`	`string`	Identifier เฉพาะของ Batch
`name`	`string`	ชื่อ Batch
`totalFiles`	`number`	จำนวนไฟล์ทั้งหมดที่ส่งเข้ามา
`completedFiles`	`number`	จำนวนไฟล์ที่ประมวลผลสำเร็จ
`failedFiles`	`number`	จำนวนไฟล์ที่ล้มเหลว
`status`	`string`	`completed` ถ้าทั้งหมดสำเร็จ, `partial` ถ้าบางส่วนล้มเหลว
`completedAt`	`string`	Timestamp ISO 8601 UTC ของเวลาที่ไฟล์สุดท้ายเสร็จสิ้น

ตัวอย่าง:

{
  "eventType": "batch.completed",
  "eventId": "evt_1743422400000_bat005",
  "timestamp": "2026-03-31T13:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "batchId": "batch_march_invoices",
    "name": "ใบแจ้งหนี้มีนาคม 2026",
    "totalFiles": 47,
    "completedFiles": 45,
    "failedFiles": 2,
    "status": "partial",
    "completedAt": "2026-03-31T13:00:00.000Z"
  }
}

Template Events

Template Events ทำงานเมื่อ Template ในองค์กรของคุณถูกสร้าง แก้ไข หรือลบ Event เหล่านี้มีประโยชน์สำหรับการ Sync Metadata ของ Template ไปยังระบบภายนอก หรือการบันทึก Audit Log

`template.created`

ทำงานเมื่อมีการสร้าง Template ใหม่ในองค์กร ใช้ Event นี้เพื่อ Sync Metadata ของ Template ไปยังระบบภายนอก หรือเริ่มต้นการตั้งค่า Downstream

Field ใน Payload:

Field	Type	คำอธิบาย
`id`	`string`	Identifier เฉพาะของ Template
`name`	`string`	ชื่อแสดงผลของ Template
`description`	`string`	คำอธิบายที่อ่านได้ว่า Template นี้ดึงข้อมูลอะไร
`projectId`	`string`	ID ของ Project ที่ Template นี้อยู่
`resultFormat`	`string`	รูปแบบ Output ที่ตั้งค่าไว้สำหรับ Template นี้ (เช่น `json`, `csv`)
`createdBy`	`string`	User ID ที่สร้าง Template
`createdAt`	`string`	Timestamp ISO 8601 UTC ของเวลาที่สร้าง

ตัวอย่าง:

{
  "eventType": "template.created",
  "eventId": "evt_1743418800000_tpl006",
  "timestamp": "2026-03-31T12:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "tmpl_invoice_v2",
    "name": "Invoice Extractor v2",
    "description": "Extracts vendor, line items, totals, and tax details from Thai-language invoices.",
    "projectId": "proj_xyz789",
    "resultFormat": "json",
    "createdBy": "user_wicha01",
    "createdAt": "2026-03-31T12:00:00.000Z"
  }
}

`template.updated`

ทำงานเมื่อมีการอัปเดต Field ใด ๆ ใน Template ไม่ว่าจะเป็นการเปลี่ยน Schema การตั้งค่าโมเดล หรือการแก้ไข Name/Description

Field ใน Payload:

Field	Type	คำอธิบาย
`id`	`string`	Identifier เฉพาะของ Template
`name`	`string`	ชื่อแสดงผลของ Template (หลังอัปเดต)
`description`	`string`	คำอธิบาย Template (หลังอัปเดต)
`projectId`	`string`	ID ของ Project ที่ Template นี้อยู่
`resultFormat`	`string`	รูปแบบ Output ที่ตั้งค่าไว้สำหรับ Template นี้
`updatedBy`	`string`	User ID ที่ทำการอัปเดต
`updatedAt`	`string`	Timestamp ISO 8601 UTC ของเวลาที่อัปเดต
`changes`	`string[]`	Array ของชื่อ Field ที่ถูกแก้ไขในการอัปเดตครั้งนี้

ตัวอย่าง:

{
  "eventType": "template.updated",
  "eventId": "evt_1743422400000_tpl007",
  "timestamp": "2026-03-31T13:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "tmpl_invoice_v2",
    "name": "Invoice Extractor v2",
    "description": "Extracts vendor, line items, totals, tax details, and payment terms from Thai-language invoices.",
    "projectId": "proj_xyz789",
    "resultFormat": "json",
    "updatedBy": "user_wicha01",
    "updatedAt": "2026-03-31T13:00:00.000Z",
    "changes": ["description", "resultFormat"]
  }
}

`template.deleted`

ทำงานเมื่อมีการลบ Template Payload เก็บข้อมูลเพียงพอสำหรับการอ้างอิง Template ที่ถูกลบแม้ว่าจะไม่มีอยู่ในระบบแล้วก็ตาม ซึ่งมีประโยชน์สำหรับการบันทึก Audit Log และการทำความสะอาด Reference ภายนอก

Field ใน Payload:

Field	Type	คำอธิบาย
`id`	`string`	Identifier เฉพาะของ Template ที่ถูกลบ
`name`	`string`	ชื่อแสดงผลของ Template ที่ถูกลบ
`projectId`	`string`	ID ของ Project ที่ Template นี้เคยอยู่
`deletedBy`	`string`	User ID ที่ลบ Template
`deletedAt`	`string`	Timestamp ISO 8601 UTC ของเวลาที่ลบ

ตัวอย่าง:

{
  "eventType": "template.deleted",
  "eventId": "evt_1743426000000_tpl008",
  "timestamp": "2026-03-31T14:00:00.000Z",
  "organizationId": "org_abc123",
  "projectId": "proj_xyz789",
  "payload": {
    "id": "tmpl_invoice_v1",
    "name": "Invoice Extractor v1",
    "projectId": "proj_xyz789",
    "deletedBy": "user_wicha01",
    "deletedAt": "2026-03-31T14:00:00.000Z"
  }
}

Documents

ประเภท Event และ Payload

ประเภท Event และ Payload

โครงสร้าง Payload มาตรฐาน

Document Events

`document.uploaded`

`document.processed`

`document.failed`

Batch Events

`batch.uploaded`

`batch.completed`

Template Events

`template.created`

`template.updated`

`template.deleted`

Table of Contents