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

Webhooks

รับการแจ้งเตือนแบบทันทีเกี่ยวกับเหตุการณ์การชำระเงิน การอัปเดตการเรียกเก็บเงิน และกิจกรรมบัญชีที่สำคัญอื่นๆ ผ่าน HTTP callbacks ที่ปลอดภัย

ภาพรวม​

Webhooks ช่วยให้แอปพลิเคชันของคุณได้รับการแจ้งเตือนแบบเรียลไทม์เมื่อเหตุการณ์เกิดขึ้นในบัญชี Omise ของคุณ แทนที่จะ poll API เพื่อตรวจสอบการเปลี่ยนแปลง Omise จะส่งคำขอ HTTP POST ไปยังจุดสิ้นสุดที่คุณระบุโดยอัตโนมัติเมื่อเหตุการณ์เกิดขึ้น

ประโยชน์หลัก:

  • การอัปเดตแบบเรียลไทม์ - การแจ้งเตือนทันทีเมื่อเหตุการณ์เกิดขึ้น
  • ลดการเรียก API - ไม่จำเป็นต้อง poll เพื่อตรวจสอบการอัปเดตสถานะ
  • การส่งที่เชื่อถือได้ - ลองใหม่อัตโนมัติเมื่อล้มเหลว
  • ปลอดภัย - การตรวจสอบลายเซ็น HMAC-SHA256
  • ครอบคลุม - รองรับประเภทเหตุการณ์มากกว่า 30 ประเภท

Webhooks ทำงานอย่างไร​

ตั้งค่า Webhooks​

การกำหนดค่าแดชบอร์ด​

  1. เข้าสู่ระบบแดชบอร์ด Omise
  2. ไปที่การตั้งค่า → Webhooks
  3. คลิก**"สร้างจุดสิ้นสุด Webhook"**
  4. ป้อน URL จุดสิ้นสุดของคุณ（ต้องเป็น HTTPS）
  5. เลือกเหตุการณ์ที่จะรับ（หรือเลือก "เหตุการณ์ทั้งหมด"）
  6. บันทึกและคัดลอก webhook secret
ต้องใช้ HTTPS

จุดสิ้นสุด Webhook ต้องใช้ HTTPS พร้อมใบรับรอง SSL ที่ถูกต้อง ไม่รองรับใบรับรองที่ลงนามด้วยตนเอง

การใช้งานจุดสิ้นสุด Webhook​

ตัวอย่าง Express.js พื้นฐาน​

const express = require('express');
const crypto = require('crypto');

const app = express();

// สำคัญ: ใช้ raw body สำหรับการตรวจสอบลายเซ็น
app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf.toString('utf8');
    }
}));

app.post('/webhooks/omise', (req, res) => {
    // 1. ตรวจสอบลายเซ็น webhook
    if (!verifyWebhookSignature(req)) {
        console.error('ลายเซ็น webhook ไม่ถูกต้อง');
        return res.sendStatus(401);
    }

    // 2. รับข้อมูลเหตุการณ์
    const event = req.body;
    console.log('ได้รับเหตุการณ์:', event.key);

    // 3. จัดการประเภทเหตุการณ์ต่างๆ
    switch (event.key) {
        case 'charge.complete':
            handleChargeComplete(event.data);
            break;

        case 'charge.failed':
            handleChargeFailed(event.data);
            break;

        case 'refund.create':
            handleRefundCreate(event.data);
            break;

        // เพิ่ม event handlers เพิ่มเติม...

        default:
            console.log('ประเภทเหตุการณ์ที่ไม่ได้จัดการ:', event.key);
    }

    // 4. ตอบกลับด้วย 200 เสมอ
    res.sendStatus(200);
});

function verifyWebhookSignature(req) {
    const signatureHeader = req.headers['x-omise-signature'];
    const rawBody = req.rawBody;

    if (!signatureHeader || !rawBody) {
        return false;
    }

    const secret = Buffer.from(process.env.OMISE_WEBHOOK_SECRET, 'base64');

    const expectedBuffer = crypto
        .createHmac('sha256', secret)
        .update(rawBody)
        .digest();

    const signatures = signatureHeader.split(',');
    for (const sig of signatures) {
        const sigBuffer = Buffer.from(sig, 'hex');
        if (crypto.timingSafeEqual(sigBuffer, expectedBuffer)) {
            return true;
        }
    }

    return false;
}

app.listen(3000);

เหตุการณ์ Webhook​

เหตุการณ์การเรียกเก็บเงิน​

เหตุการณ์คำอธิบาย
charge.createสร้างการเรียกเก็บเงิน
charge.completeการชำระเงินเสร็จสมบูรณ์
charge.failedการชำระเงินล้มเหลว
charge.expireการอนุมัติหมดอายุ (ยังไม่ได้ capture)
charge.reverseการเรียกเก็บเงินถูกย้อนกลับ
charge.captureการเรียกเก็บเงินที่ได้รับอนุมัติล่วงหน้าถูก capture
charge.updateอัปเดตการเรียกเก็บเงิน

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

เหตุการณ์คำอธิบาย
customer.createสร้างลูกค้า
customer.updateอัปเดตข้อมูลลูกค้า
customer.update.cardอัปเดตบัตรของลูกค้า
customer.destroyลบลูกค้า

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

เหตุการณ์คำอธิบาย
card.updateอัปเดตข้อมูลบัตร
card.destroyลบบัตรจากลูกค้า

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

เหตุการณ์คำอธิบาย
refund.createสร้างและประมวลผลการคืนเงิน

แนวทางปฏิบัติที่ดีด้านความปลอดภัย​

1. ตรวจสอบลายเซ็นเสมอ​

อย่าข้ามการตรวจสอบลายเซ็นเด็ดขาด! สิ่งนี้ป้องกันไม่ให้ผู้โจมตีส่ง webhooks ปลอม

2. ใช้ HTTPS​

  • จุดสิ้นสุด webhook ทั้งหมดต้องใช้ HTTPS
  • ใช้ใบรับรอง SSL ที่ถูกต้อง (ไม่ใช่ self-signed)
  • ทดสอบด้วยSSL Labs

3. ตอบสนองอย่างรวดเร็ว​

app.post('/webhooks/omise', async (req, res) => {
    // ตรวจสอบลายเซ็น
    if (!verifyWebhookSignature(req)) {
        return res.sendStatus(401);
    }

    // ตอบกลับทันที
    res.sendStatus(200);

    // ประมวลผลเหตุการณ์แบบอะซิงโครนัส
    processWebhookAsync(req.body).catch(err => {
        console.error('ข้อผิดพลาดในการประมวลผล webhook:', err);
    });
});

การทดสอบ​

การทดสอบในเครื่องด้วย ngrok​

# ติดตั้ง ngrok
npm install -g ngrok

# เริ่มเซิร์ฟเวอร์ในเครื่อง
node server.js # ทำงานบนพอร์ต 3000

# สร้างอุโมงค์
ngrok http 3000

# ใช้ URL HTTPS ในแดชบอร์ด Omise
# ตัวอย่าง: https://abc123.ngrok.io/webhooks/omise

คำถามที่พบบ่อย​

Omise ใช้ที่อยู่ IP ใดสำหรับ webhooks?

Omise ไม่เผยแพร่รายการที่อยู่ IP คงที่สำหรับ webhooks แทนที่จะใช้การตรวจสอบลายเซ็น (HMAC-SHA256) เพื่อตรวจสอบ webhooks ซึ่งปลอดภัยกว่าการ whitelist IP

ฉันสามารถมีจุดสิ้นสุด webhook หลายจุดได้หรือไม่?

ได้! คุณสามารถกำหนดค่าจุดสิ้นสุด webhook หลายจุดในแดชบอร์ด แต่ละจุดสามารถสมัครรับเหตุการณ์ที่แตกต่างกัน นี่มีประโยชน์สำหรับ:

  • จุดสิ้นสุดแยกสำหรับบริการต่างๆ
  • สภาพแวดล้อมการพัฒนา/staging/production
  • จุดสิ้นสุดสำรองเพื่อความซ้ำซ้อน

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

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

  1. ตั้งค่าจุดสิ้นสุด webhook
  2. ใช้การตรวจสอบลายเซ็น
  3. จัดการเหตุการณ์หลัก
  4. ทดสอบด้วย ngrok
  5. เผยแพร่สู่ production