वेबहुक (Webhooks)

वेबहुक (Webhooks) वास्तविक समय HTTP POST सूचनाएं देते हैं जब पृष्ठभूमि के एसिंक्रोनस कार्य पूरे हो जाते हैं, जैसे कि सफल पोस्ट प्रकाशन, विफलताएं, या उत्तर प्रेषण।

---

📌 एंडपॉइंट्स (Endpoints)

विधि (Method)	पाथ (Path)	विवरण (Description)	आवश्यक स्कोप (Required Scope)
POST	/v1/brand/webhooks/subscriptions	नया वेबहुक एंडपॉइंट पंजीकृत करें	webhooks:write या *
GET	/v1/brand/webhooks/subscriptions	पंजीकृत वेबहुक सदस्यताएँ सूचीबद्ध करें	webhooks:read या *
DELETE	/v1/brand/webhooks/subscriptions/{id}	वेबहुक सदस्यता हटाएँ	webhooks:write या *

---

🔔 समर्थित इवेंट प्रकार (Supported Event Types)

इवेंट का नाम (Event Name)	ट्रिगर स्थिति (Trigger Condition)
sns.publish.succeeded	पोस्ट सफलतापूर्वक लक्षित सोशल नेटवर्क पर प्रकाशित हो गई
sns.publish.failed	पोस्ट प्रकाशन विफल (त्रुटि कोड और पुन: प्रयास पात्रता शामिल है)
sns.publish.blocked_entitlement	कोटा सीमा या समाप्त प्लान के कारण प्रकाशन ब्लॉक किया गया
sns.reply.succeeded	उत्तर टिप्पणी सफलतापूर्वक पोस्ट की गई
sns.reply.failed	उत्तर टिप्पणी प्रेषण विफल
sns.provider.notification_received	बाहरी SNS प्रदाता से वास्तविक समय वेबहुक प्राप्त हुआ

---

📦 वेबहुक पेलोड उदाहरण (Webhook Payload Example) (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/"
  }
}

---

🔐 हस्ताक्षर सत्यापन (Signature Verification) (HMAC SHA256)

वेबहुक अनुरोधों में कस्टम सत्यापन हेडर शामिल होते हैं:

• Social-Webhook-Signature: हस्ताक्षर पेलोड (t=1723780000,v1=hex_signature)
• Social-Webhook-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');

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

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] हस्ताक्षर सत्यापन के लिए अनपार्स्ड रॉ अनुरोध बॉडी (unparsed raw request body) का उपयोग किया जाना चाहिए।

---

🔗 संबंधित दस्तावेज़

• कंटेंट API
• टिप्पणियाँ और उत्तर API
• कतार और प्रकाशन स्थिति
• त्रुटि प्रबंधन