ข้ามไปยังเนื้อหาหลัก

ประเภทเหตุการณ์เวบฮุก

คำแนะนำอ้างอิงที่สมบูรณ์สำหรับเหตุการณ์เวบฮุกที่พร้อมใช้งานทั้งหมดใน Omise พร้อมตัวอย่างเพย์โหลดโดยละเอียดและแนวทางการผสานรวม

ภาพรวม​

Omise ส่งเหตุการณ์เวบฮุกสำหรับกิจกรรมการชำระเงินและบัญชีต่างๆ แต่ละเหตุการณ์มี:

  • Event key: ตัวระบุเฉพาะสำหรับประเภทเหตุการณ์ (เช่น charge.complete)
  • Event ID: ตัวระบุเฉพาะสำหรับการเกิดเหตุการณ์นี้
  • Created timestamp: เมื่อเหตุการณ์เกิดขึ้น
  • Data object: ออบเจ็กต์ทรัพยากรเต็มที่เกี่ยวข้องกับเหตุการณ์
  • API version: เวอร์ชัน Omise API ที่ใช้

หมวดหมู่เหตุการณ์​

เหตุการณ์จัดเป็นหมวดหมู่เหล่านี้:

  • เหตุการณ์การชำระเงิน - การสร้าง, การทำให้เสร็จสิ้น และการเปลี่ยนสถานะ
  • เหตุการณ์ลูกค้า - การสร้างและอัปเดตโปรไฟล์
  • เหตุการณ์บัตร - การสร้างและอัปเดตบัตร
  • เหตุการณ์การคืนเงิน - การสร้างและการทำให้เสร็จสิ้น
  • เหตุการณ์การโอน - การสร้าง, การอัปเดต และการตั้งถิ่นฐาน
  • เหตุการณ์ผู้รับ - การสร้างและอัปเดตโปรไฟล์
  • เหตุการณ์ข้อพิพาท - การสร้าง, การอัปเดต และการแก้ไข
  • เหตุการณ์ลิงก์ - การสร้างลิงก์และการชำระเงิน
  • เหตุการณ์กำหนดเวลา - การสร้าง, การทำให้เสร็จสิ้น และการหมดอายุ

เหตุการณ์การชำระเงิน​

charge.create​

เรียกใช้เมื่อสร้างประจำใหม่

กรณีการใช้:

  • บันทึกการสร้างประจำสำหรับบันทึกตรวจสอบ
  • ติดตามเมตริกการเริ่มต้นการชำระเงิน
  • อัปเดตสถานะคำสั่งซื้อเป็น "processing"

ตัวอย่างเพย์โหลด:

{
  "object": "event",
  "id": "evnt_test_5xq6zfg18b4bxg37kjh",
  "key": "charge.create",
  "created_at": "2024-02-06T10:30:00Z",
  "data": {
    "object": "charge",
    "id": "chrg_test_5xq6zfexznf7wjh0aj3",
    "amount": 100000,
    "currency": "THB",
    "status": "pending",
    "metadata": {
      "order_id": "1234"
    }
  }
}

charge.complete​

เรียกใช้เมื่อการชำระเงินเสร็จสิ้นสำเร็จ

กรณีการใช้:

  • ทำให้คำสั่งซื้อเสร็จสิ้นและจัดส่งสินค้า
  • ส่งอีเมลยืนยันการชำระเงิน
  • อัปเดตระบบบัญชี
  • ให้สิทธิ์การเข้าถึงสินค้าดิจิทัล

charge.expire​

เรียกใช้เมื่อประจำหมดอายุโดยไม่มีการชำระเงิน

charge.capture​

เรียกใช้เมื่อประจำที่ได้รับอนุมัติได้รับการจับขาด

charge.reverse​

เรียกใช้เมื่อประจำที่ได้รับอนุมัติถูกย้อนกลับ

เหตุการณ์ลูกค้า​

customer.create​

เรียกใช้เมื่อสร้างลูกค้าใหม่

ตัวอย่างเพย์โหลด:

{
  "object": "event",
  "key": "customer.create",
  "created_at": "2024-02-06T10:00:00Z",
  "data": {
    "object": "customer",
    "id": "cust_test_5xq6zfexznf7wjh0aj3",
    "email": "john.doe@example.com",
    "metadata": {
      "user_id": "12345"
    }
  }
}

customer.update​

เรียกใช้เมื่ออัปเดตรายละเอียดลูกค้า

customer.destroy​

เรียกใช้เมื่อลบลูกค้า

เหตุการณ์บัตร​

card.create​

เรียกใช้เมื่อเพิ่มบัตรสำหรับลูกค้า

card.update​

เรียกใช้เมื่ออัปเดตรายละเอียดบัตร

card.destroy​

เรียกใช้เมื่อลบบัตรจากลูกค้า

เหตุการณ์การคืนเงิน​

refund.create​

เรียกใช้เมื่อสร้างการคืนเงิน

กรณีการใช้:

  • อัปเดตสถานะคำสั่งซื้อเป็นคืนเงิน
  • ประมวลผลการคืนสินค้า
  • ส่งอีเมลยืนยันการคืนเงิน
  • อัปเดตบันทึกบัญชี

refund.update​

เรียกใช้เมื่อเปลี่ยนสถานะการคืนเงิน

เหตุการณ์การโอน​

transfer.create​

เรียกใช้เมื่อสร้างการโอน

transfer.update​

เรียกใช้เมื่อเปลี่ยนสถานะการโอน

transfer.destroy​

เรียกใช้เมื่อยกเลิกการโอนที่กำหนดเวลา

เหตุการณ์ผู้รับ​

recipient.create​

เรียกใช้เมื่อสร้างผู้รับใหม่

recipient.update​

เรียกใช้เมื่ออัปเดตรายละเอียดผู้รับ

recipient.destroy​

เรียกใช้เมื่อลบผู้รับ

เหตุการณ์ข้อพิพาท​

dispute.create​

เรียกใช้เมื่อลูกค้าเปิดข้อพิพาท

กรณีการใช้:

  • แจ้งเตือนทีมการเงิน
  • รวบรวมหลักฐานสำหรับการตอบสนองข้อพิพาท
  • ระงับบริการที่เกี่ยวข้องหากจำเป็น
  • ติดตามเมตริกข้อพิพาท

ตัวอย่างเพย์โหลด:

{
  "object": "event",
  "key": "dispute.create",
  "created_at": "2024-02-10T10:00:00Z",
  "data": {
    "object": "dispute",
    "id": "dspt_test_5xq6zfexznf7wjh0aj3",
    "amount": 100000,
    "currency": "THB",
    "status": "open",
    "charge": "chrg_test_5xq6zfexznf7wjh0aj3",
    "reason_code": "fraudulent",
    "respond_by": "2024-02-17T23:59:59Z"
  }
}

dispute.update​

เรียกใช้เมื่อเปลี่ยนสถานะข้อพิพาท

dispute.close​

เรียกใช้เมื่อปิดข้อพิพาท (ชนะ, แพ้ หรือถอนตัว)

เหตุการณ์ลิงก์​

link.create​

เรียกใช้เมื่อสร้างลิงก์การชำระเงิน

link.payment.create​

เรียกใช้เมื่อมีการชำระเงินผ่านลิงก์การชำระเงิน

เหตุการณ์กำหนดเวลา​

schedule.create​

เรียกใช้เมื่อสร้างกำหนดเวลา

schedule.update​

เรียกใช้เมื่ออัปเดตรายละเอียดกำหนดเวลา

schedule.expiration.close​

เรียกใช้เมื่อกำหนดเวลาถึงวันที่สิ้นสุด

การจัดการเหตุการณ์​

การกำหนดเส้นทางของเหตุการณ์ทั่วไป​

// Node.js - การจัดการเหตุการณ์หลาย
async function handleWebhook(event) {
  switch (event.key) {
    case 'charge.complete':
      return handleChargeComplete(event.data);
    case 'charge.expire':
      return handleChargeExpire(event.data);
    case 'refund.create':
      return handleRefundCreate(event.data);
    case 'dispute.create':
      return handleDisputeCreate(event.data);
    default:
      console.log(`Unknown event: ${event.key}`);
  }
}

การตรวจสอบข้อมูลเหตุการณ์​

# Python - ตรวจสอบข้อมูลเวบฮุก
from marshmallow import Schema, fields, ValidationError

class ChargeSchema(Schema):
    id = fields.Str(required=True)
    amount = fields.Int(required=True)
    currency = fields.Str(required=True)
    status = fields.Str(required=True)

def validate_webhook(event):
    try:
        if event['key'].startswith('charge.'):
            ChargeSchema().load(event['data'])
        return True
    except ValidationError as err:
        print(f'Invalid data: {err.messages}')
        return False

แนวทางปฏิบัติที่ดี​

การประมวลผลเหตุการณ์​

  • ตรวจสอบลายเซ็น สำหรับเหตุการณ์ทั้งหมด
  • ตอบสนองอย่างรวดเร็ว (ภายใน 10 วินาที)
  • ประมวลผลแบบไม่ซิงโครนัส โดยใช้คิวงาน
  • ใช้ความเป็นปัญหาเดียวกัน เพื่อจัดการเหตุการณ์ที่ซ้ำกัน
  • บันทึกทั้งหมด เพื่อการแก้ไขปัญหาและบันทึกตรวจสอบ

การจัดการข้อผิดพลาด​

  • ไม่ฉาดเหตุการณ์ที่ไม่คุ้นเคย - บันทึกและตอบ 200 OK
  • ตรวจสอบสตรีมเหตุการณ์ - ใช้ timestamp เพื่อตรวจสอบลำดับ
  • แจ้งแบบมีเงื่อนไข - บันทึกรูปแบบข้อผิดพลาด

ทรัพยากรที่เกี่ยวข้อง​

ขั้นตอนถัดไป​

  1. ศึกษาเหตุการณ์ของคุณ ที่แอปพลิเคชันจัดการ
  2. ใช้ตัวจัดการเหตุการณ์ สำหรับแต่ละประเภท
  3. ทดสอบสถานการณ์ทั้งหมด ในโหมดการทดสอบ
  4. ใช้การตรวจสอบลายเซ็น สำหรับความปลอดภัย
  5. บันทึกเหตุการณ์ทั้งหมด สำหรับการแก้ไขปัญหา

ต้องการสิ่งดีๆหรือไม่ ดูความปลอดภัย

ต้องการสิ่งสำหรับการลองใหม่ ดูลอจิกการลองใหม่