Webhook

Webhook จะส่งการแจ้งเตือน HTTP POST แบบเรียลไทม์เมื่องานเบื้องหลังแบบอะซิงโครนัสเสร็จสิ้น เช่น การเผยแพร่สำเร็จ การเผยแพร่ล้มเหลว หรือการส่งคำตอบกลับ

---

📌 Endpoint

เมธอด	พาธ	คำอธิบาย	ขอบเขตสิทธิ์ที่จำเป็น
POST	/v1/brand/webhooks	ลงทะเบียน Endpoint ของ Webhook ใหม่	webhooks:write หรือ *
GET	/v1/brand/webhooks	แสดงรายการ Webhook ที่ลงทะเบียนไว้	webhooks:read หรือ *
DELETE	/v1/brand/webhooks/{webhook_id}	ลบ Webhook ที่ลงทะเบียนไว้	webhooks:write หรือ *

---

🔔 ประเภทเหตุการณ์ที่รองรับ

ชื่อเหตุการณ์	เงื่อนไขการเกิด
sns.publish.succeeded	เผยแพร่โพสต์ไปยังเครือข่ายสังคมเป้าหมายสำเร็จ
sns.publish.failed	การเผยแพร่โพสต์ล้มเหลว (รวมรหัสข้อผิดพลาดและสิทธิ์การลองใหม่)
sns.publish.blocked_entitlement	การเผยแพร่ถูกบล็อกเนื่องจากเกินขีดจำกัดโควตาหรือแผนบริการหมดอายุ
sns.reply.succeeded	โพสต์คอมเมนต์ตอบกลับสำเร็จ
sns.reply.failed	การส่งคอมเมนต์ตอบกลับล้มเหลว
sns.provider.notification_received	ได้รับ Webhook แบบเรียลไทม์จากผู้ให้บริการ SNS ภายนอก

---

📦 ตัวอย่างเพย์โหลด Webhook (sns.publish.succeeded)

{
  "event_id": "evt_01jm8za2example",
  "event_type": "sns.publish.succeeded",
  "schema_version": 1,
  "occurred_at": "2026-08-16T03:30:00Z",
  "brand_ref": "brand_01jm8v4k9example",
  "trace_id": "trc_9a8b7c6d",
  "data": {
    "content_id": "content_01jm8za2example",
    "publish_job_id": "job_01jm8za2jobexample",
    "sns_type": "instagram",
    "connection_id": "conn_01jm8x9k2example",
    "provider_post_id": "18029384756102938",
    "status": "succeeded"
  }
}

---

🔐 การตรวจสอบลายเซ็น (HMAC SHA256)

คำขอ Webhook มีส่วนหัวสำหรับการตรวจสอบดังนี้:

• Social-Webhook-Signature: ข้อมูลลายเซ็น (v1=hex_signature)
• Social-Webhook-Timestamp: Unix timestamp ในหน่วยวินาที
• Social-Webhook-Id: รหัสการส่ง

การตรวจสอบด้วย Node.js (Crypto)

import crypto from 'node:crypto';

export function verifyWebhookSignature(rawBody: string, signatureHeader: string, timestampHeader: string, secret: string): boolean {
  const signedPayload = `${timestampHeader}.${rawBody}`;
  const expectedSignature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');

  const actual = Buffer.from(signatureHeader);
  const expected = Buffer.from(`v1=${expectedSignature}`);
  return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
}

การตรวจสอบด้วย Python (hmac)

import hmac
import hashlib

def verify_webhook_signature(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signed_payload = f"{timestamp}.".encode('utf-8') + raw_body
    expected = hmac.new(secret.encode('utf-8'), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, f"v1={expected}")

[!CAUTION] การตรวจสอบลายเซ็นต้องใช้ เนื้อหาคำขอดิบที่ยังไม่ได้แยกวิเคราะห์

---

🔗 เอกสารที่เกี่ยวข้อง

• API เนื้อหา
• API ความคิดเห็นและการตอบกลับ
• คิวและสถานะการเผยแพร่
• การจัดการข้อผิดพลาด