ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

API Webhook Secrets

Interactive Webhook Tester​

Explore webhook events, view example payloads, and test your endpoint:

ตัวทดสอบ Webhook แบบโต้ตอบ

สำรวจ Webhook events และทดสอบ endpoint ของคุณ

Triggered when a charge is completed successfully

POSTcharge.complete
{
  "object": "event",
  "id": "evnt_test_5h2m123lxlx4z7yh9a2",
  "livemode": false,
  "location": "/events/evnt_test_5h2m123lxlx4z7yh9a2",
  "webhook_deliveries": [],
  "data": {
    "object": "charge",
    "id": "chrg_test_5h2m123abc456def",
    "amount": 100000,
    "currency": "thb",
    "description": "Test charge",
    "status": "successful",
    "authorized": true,
    "paid": true,
    "captured": true,
    "capture": true,
    "refunded": 0,
    "reversed": false,
    "voided": false,
    "expired": false,
    "disputable": true,
    "capturable": false,
    "reversible": false,
    "transaction": "trxn_test_5h2m123abc456def",
    "source_of_fund": "card",
    "failure_code": null,
    "failure_message": null,
    "card": {
      "object": "card",
      "id": "card_test_5h2m123abc456def",
      "livemode": false,
      "brand": "Visa",
      "last_digits": "4242",
      "name": "Test User",
      "expiration_month": 12,
      "expiration_year": 2025,
      "fingerprint": "FpEYKqwFa3znwjpHlEHjHg==",
      "security_code_check": true
    },
    "created_at": "2026-03-09T09:56:17.705Z"
  },
  "key": "charge.complete",
  "created_at": "2026-03-09T09:56:17.705Z"
}

API Webhook Secrets ช่วยให้คุณจัดการ signing secrets ที่ใช้ในการยืนยันความถูกต้องของ webhook แต่ละเหตุการณ์ webhook ที่ส่งโดย Omise จะมีลายเซ็นที่คุณสามารถตรวจสอบได้โดยใช้ signing secret เพื่อให้แน่ใจว่าเหตุการณ์มาจาก Omise จริงๆ

ภาพรวม​

Webhook secrets ให้:

  • ความถูกต้องของเหตุการณ์ - ยืนยันว่า webhooks มาจาก Omise ไม่ใช่ผู้โจมตี
  • การตรวจจับการดัดแปลง - ตรวจจับว่า webhook payloads ถูกแก้ไขหรือไม่
  • หลาย secrets - รองรับการหมุนเวียนคีย์โดยไม่มีการหยุดทำงาน
  • การจัดการคีย์ที่ปลอดภัย - สร้าง แสดงรายการ และลบ secrets ผ่านโปรแกรม

วิธีการทำงานของลายเซ็น Webhook​

  1. การสร้าง Secret - สร้าง signing secret ผ่าน API
  2. การสร้างลายเซ็น - Omise ลงนามแต่ละ webhook โดยใช้ secret ของคุณ
  3. การยืนยันลายเซ็น - เซิร์ฟเวอร์ของคุณตรวจสอบลายเซ็นก่อนการประมวลผล
  4. การหมุนเวียน Secret - หมุนเวียน secrets เป็นระยะเพื่อเพิ่มความปลอดภัย

โครงสร้างลายเซ็น Webhook​

แต่ละคำขอ webhook จะมีส่วนหัวลายเซ็น:

  • Omise-Signature - ลายเซ็น HMAC-SHA256 ที่เข้ารหัสเป็น hex (อาจมีสองลายเซ็นที่คั่นด้วยเครื่องหมายจุลภาคในระหว่างการหมุนเวียน secret)
  • Omise-Signature-Timestamp - Unix timestamp เมื่อลายเซ็นถูกสร้าง

การยืนยันลายเซ็น Webhook​

เพื่อยืนยันลายเซ็น webhook:

  1. ดึง timestamp และลายเซ็นจากส่วนหัว
  2. ต่อ timestamp และ raw request body
  3. คำนวณ HMAC-SHA256 โดยใช้ signing secret ของคุณ
  4. เปรียบเทียบลายเซ็นที่คำนวณกับลายเซ็นที่ได้รับ
  5. ยืนยันว่า timestamp ล่าสุด (ภายใน 5 นาที) เพื่อป้องกันการโจมตีซ้ำ
import hmac
import hashlib
import time

def verify_webhook(payload, signature, timestamp, secret):
    # ตรวจสอบว่า timestamp อยู่ภายใน 5 นาที
    current_time = int(time.time())
    if abs(current_time - int(timestamp)) > 300:
        return False

    # คำนวณลายเซ็นที่คาดหวัง
    message = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    # เปรียบเทียบลายเซ็นอย่างปลอดภัย
    return hmac.compare_digest(expected_sig, signature)

โครงสร้างอ็อบเจกต์ Secret​

แต่ละ webhook secret ประกอบด้วย:

  • Secret ID - ตัวระบุเฉพาะ (whsec_*)
  • Secret Value - signing key (แสดงเฉพาะตอนสร้าง)
  • Created At - เวลาที่ secret ถูกสร้าง
  • Livemode - เป็น secret โหมดจริงหรือโหมดทดสอบ

กรณีใช้งานหลัก​

การยืนยัน Webhook​

ยืนยันว่า webhooks ที่เข้ามามาจาก Omise จริงก่อนการประมวลผล

การหมุนเวียนคีย์​

สร้าง secret ใหม่ อัปเดตโค้ดยืนยันให้รับทั้งสองอัน แล้วลบ secret เก่า

การปฏิบัติตามความปลอดภัย​

รักษาบันทึกการตรวจสอบของการสร้างและลบ secret สำหรับข้อกำหนดการปฏิบัติตาม

การตั้งค่าหลายสภาพแวดล้อม​

ใช้ secrets แยกสำหรับสภาพแวดล้อมการพัฒนา staging และ production

Endpoints ที่พร้อมใช้งาน​

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

ควรทำ​

  • ยืนยันลายเซ็นเสมอก่อนประมวลผล webhooks
  • ตรวจสอบ timestamps เพื่อป้องกันการโจมตีซ้ำ
  • หมุนเวียน secrets เป็นระยะ (แนะนำทุก 90 วัน)
  • รองรับหลาย secrets ในช่วงการหมุนเวียน
  • เก็บ secrets อย่างปลอดภัยในตัวแปรสภาพแวดล้อมหรือตัวจัดการ secrets
  • ใช้การเปรียบเทียบเวลาคงที่เพื่อป้องกันการโจมตีแบบ timing

ไม่ควรทำ​

  • อย่าบันทึก secrets ในบันทึกแอปพลิเคชัน
  • อย่า hardcode secrets ในซอร์สโค้ด
  • อย่าข้ามการยืนยันแม้ในสภาพแวดล้อมการพัฒนา
  • อย่าเพิกเฉยการตรวจสอบ timestamp เพราะป้องกันการโจมตีซ้ำ
  • อย่าแชร์ secrets ข้ามสภาพแวดล้อม

ข้อพิจารณาด้านความปลอดภัย​

การเก็บรักษา Secret​

  • เก็บ secrets ในระบบจัดการ secrets ที่ปลอดภัย (AWS Secrets Manager, HashiCorp Vault ฯลฯ)
  • อย่า commit secrets ไปยัง version control
  • ใช้ตัวแปรสภาพแวดล้อมสำหรับการ deploy

การหมุนเวียนคีย์​

  • สร้าง secret ใหม่ก่อนลบอันเก่า
  • อัปเดตโค้ดยืนยันให้ตรวจสอบทั้งสอง secrets ในระหว่างการเปลี่ยนผ่าน
  • ลบ secret เก่าหลังจากยืนยันว่า secret ใหม่ใช้งานได้
  • ตั้งเป้าให้หมุนเวียนเสร็จภายใน 24-48 ชั่วโมง

การป้องกันการโจมตีซ้ำ​

  • ตรวจสอบส่วนหัว timestamp เสมอ
  • ปฏิเสธ webhooks ที่มี timestamps เก่ากว่า 5 นาที
  • พิจารณาใช้ idempotency ตาม event IDs

แหล่งข้อมูลที่เกี่ยวข้อง​

ต้องการความช่วยเหลือ? ดู คู่มือ Webhooks หรือติดต่อ support@omise.co