Webhooks

Webhook cung cấp thông báo HTTP POST theo thời gian thực khi các tác vụ nền không đồng bộ hoàn tất, chẳng hạn như đăng bài thành công, thất bại hoặc gửi phản hồi.

---

📌 Điểm cuối

Phương thức	Đường dẫn	Mô tả	Scope yêu cầu
POST	/v1/brand/webhooks/subscriptions	Đăng ký một điểm cuối webhook mới	webhooks:write hoặc *
GET	/v1/brand/webhooks/subscriptions	Liệt kê các đăng ký webhook đã đăng ký	webhooks:read hoặc *
DELETE	/v1/brand/webhooks/subscriptions/{id}	Xóa một đăng ký webhook	webhooks:write hoặc *

---

🔔 Các loại sự kiện được hỗ trợ

Tên sự kiện	Điều kiện kích hoạt
sns.publish.succeeded	Bài viết đã được xuất bản thành công lên mạng xã hội mục tiêu
sns.publish.failed	Xuất bản bài viết thất bại (bao gồm mã lỗi và khả năng thử lại)
sns.publish.blocked_entitlement	Việc xuất bản bị chặn do giới hạn hạn ngạch hoặc gói đã hết hạn
sns.reply.succeeded	Bình luận phản hồi đã được đăng thành công
sns.reply.failed	Việc gửi bình luận phản hồi thất bại
sns.provider.notification_received	Nhận được webhook theo thời gian thực từ nhà cung cấp SNS bên ngoài

---

📦 Ví dụ Payload Webhook (sns.publish.succeeded)

{
  "event_id": "evt_01jm8za2example",
  "event_type": "sns.publish.succeeded",
  "schema_version": 1,
  "occurred_at": "2026-08-16T03:30:00Z",
  "producer": "ankk.sns",
  "brand_ref": "brand_01jm8v4k9example",
  "idempotency_key": "launch-2026-001",
  "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",
    "permalink": "https://www.instagram.com/p/C-example/"
  }
}

---

🔐 Xác minh chữ ký (HMAC SHA256)

Các yêu cầu Webhook bao gồm các tiêu đề xác minh tùy chỉnh:

• Social-Webhook-Signature: Payload chữ ký (t=1723780000,v1=hex_signature)
• Social-Webhook-Timestamp: Dấu thời gian Unix tính bằng giây
• Social-Webhook-Id: Mã định danh sự kiện

Xác minh 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');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

Xác minh 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, expected)

[!CAUTION] Việc xác minh chữ ký phải sử dụng thân yêu cầu thô chưa được phân tích (unparsed raw request body).

---

🔗 Tài liệu liên quan

• API Nội dung
• API Bình luận & Phản hồi
• Hàng đợi & Trạng thái Xuất bản
• Xử lý lỗi