वेबहुक

एक वेबहुक आपके वर्कस्पेस में कुछ होते ही आपके सर्वर को एक HTTPS रिक्वेस्ट भेजता है। API को पोल करने की बजाय वेबहुक इस्तेमाल करें: जब कोई कॉल खत्म होती है, तो आपको सारांश, नतीजा, इकट्ठा किए गए विवरण और ट्रांसक्रिप्ट तुरंत मिलते हैं। हर डिलीवरी एक सीक्रेट से साइन की जाती है जिसे सिर्फ़ आप और Ringhum जानते हैं, ताकि आपका सर्वर उस किसी भी चीज़ को अस्वीकार कर सके जो Ringhum से नहीं आई।

एक एंडपॉइंट जोड़ें

सिर्फ़ वर्कस्पेस का ओनर और एडमिन ही एंडपॉइंट जोड़, टेस्ट और हटा सकते हैं।

1. साइडबार में डेवलपर्स खोलें।
2. वेबहुक कार्ड में, एंडपॉइंट जोड़ें पर क्लिक करें।
3. एंडपॉइंट URL डालें। यह https:// से शुरू होना चाहिए।
4. इवेंट के तहत, जो इवेंट आप चाहते हैं उन पर टिक करें। call.ended आपके लिए टिक किया हुआ है।
5. एंडपॉइंट जोड़ें पर क्लिक करें।
6. हरे बॉक्स से साइनिंग सीक्रेट कॉपी करें (यह whsec_ से शुरू होता है) और इसे अपने सर्वर पर रखें। Done पर क्लिक करें।

ज़रूरी: साइनिंग सीक्रेट सिर्फ़ एक बार दिखाया जाता है। अगर आप इसे खो देते हैं, तो एंडपॉइंट हटाएं और नया सीक्रेट पाने के लिए इसे फिर से जोड़ें।

आप जितने चाहें उतने एंडपॉइंट जोड़ सकते हैं। वेबहुक वर्कस्पेस के हर असिस्टेंट को कवर करते हैं। आप write स्कोप वाली कुंजी के साथ POST /webhooks का इस्तेमाल करके API से भी एंडपॉइंट मैनेज कर सकते हैं।

इवेंट

एक डिलीवरी कैसी दिखती है

हर डिलीवरी एक JSON बॉडी और इन हेडर के साथ एक POST है:

POST https://example.com/hooks/ringhum
Content-Type: application/json
User-Agent: Ringhum-Webhooks/1.0
X-Ringhum-Event: call.ended
X-Ringhum-Timestamp: 1789250000
X-Ringhum-Signature: v1=5f1a…

{
  "id": "evt_8f2k…",
  "type": "call.ended",
  "created_at": "2026-09-24T14:03:11+00:00",
  "data": {
    "call_id": 4812,
    "direction": "inbound",
    "from": "+14155550132",
    "to": "+14155550100",
    "assistant_id": 3,
    "status": "completed",
    "outcome": "message_taken",
    "sentiment": "neutral",
    "duration_seconds": 94,
    "summary": "Caller asked for a quote for a kitchen repair…",
    "extracted": { "name": "Dana Lee", "reason": "Quote" },
    "transcript": [
      { "role": "assistant", "content": "Hello, you've reached…" },
      { "role": "user", "content": "Hi, I'd like a quote…" }
    ]
  }
}

data ऑब्जेक्ट इवेंट पर निर्भर करता है:

• call.ended और message.taken: ऊपर वाले कॉल फ़ील्ड।
• call.started और call.transferred: call_id, direction, from, to, assistant_id, status और started_at।
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (नाम, फ़ोन, ईमेल), contact_id, service, staff, call_id और notes।
• order.*: order_id, number, status, fulfillment, customer, address, विकल्प व कीमतों के साथ items, currency, subtotal, fee, total, source, call_id और, रद्दीकरण के लिए, cancel_reason।
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total और source।
• campaign.completed: campaign_id, name और कैंपेन की प्रगति की गिनती।

नोट: जब असिस्टेंट कॉल के दौरान एक अपॉइंटमेंट बुक करता है, तो आपको appointment.booked दो बार मिल सकता है। एक बुकिंग होते ही भेजा जाता है, अपॉइंटमेंट फ़ील्ड के साथ। दूसरा कॉल का सारांश बनने के बाद भेजा जाता है, कॉल फ़ील्ड के साथ। जांचें कि data में appointment_id है या call_id, और एक डिलीवरी को दो बार प्रोसेस करने से बचने के लिए id फ़ील्ड इस्तेमाल करें।

सिग्नेचर जांचें

सिग्नेचर टाइमस्टैंप, एक डॉट, और कच्ची रिक्वेस्ट बॉडी का एक HMAC-SHA256 है, जो आपके एंडपॉइंट के साइनिंग सीक्रेट से की-युक्त है। यह v1= के बाद हेक्स डाइजेस्ट के रूप में भेजा जाता है।

1. किसी भी JSON पार्सिंग से पहले, कच्ची बॉडी को बिल्कुल वैसे ही पढ़ें जैसे प्राप्त हुई।
2. स्ट्रिंग {X-Ringhum-Timestamp}.{raw body} बनाएं।
3. अपने सीक्रेट से HMAC-SHA256 निकालें और इसके आगे v1= जोड़ें।
4. इसे कॉन्स्टेंट-टाइम तुलना का इस्तेमाल करके X-Ringhum-Signature से मिलाएं।
5. अगर टाइमस्टैंप पांच मिनट से ज़्यादा पुराना है, तो रिक्वेस्ट को अस्वीकार करें, ताकि दोहराई गई रिक्वेस्ट रोकी जा सकें।

Node.js:

const crypto = require('crypto');

function isValid(req, rawBody, secret) {
  const ts = req.header('X-Ringhum-Timestamp');
  const sig = req.header('X-Ringhum-Signature') || '';
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

PHP:

$ts = $_SERVER['HTTP_X_RINGHUM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RINGHUM_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

रिस्पॉन्स, टाइमआउट और रीट्राई

• डिलीवरी की पुष्टि के लिए किसी भी 2xx स्टेटस से जवाब दें। जवाब देने के बाद धीमा काम करें।
• Ringhum आपके रिस्पॉन्स के लिए 10 सेकंड तक इंतज़ार करता है।
• अगर आपका एंडपॉइंट 2xx से जवाब नहीं देता, तो डिलीवरी कुल मिलाकर 3 बार तक आज़माई जाती है: तुरंत, फिर लगभग 10 सेकंड बाद, और आख़िरी बार लगभग 60 सेकंड बाद। इसके बाद इसे छोड़ दिया जाता है।
• डिलीवरी बेतरतीब क्रम में आ सकती हैं। इन्हें क्रम में रखने के लिए created_at और data में मौजूद आईडी इस्तेमाल करें।

वेबहुक टेबल हर एंडपॉइंट की आख़िरी HTTP स्थिति और यह कब भेजी गई, दिखाती है। एक फेल हुआ एंडपॉइंट सक्रिय बना रहता है; Ringhum इसे आपके लिए बंद नहीं करता।

टेस्ट, रोकें और हटाएं

• टेस्ट भेजें तुरंत एक test.ping इवेंट भेजता है, और एक मैसेज आपके एंडपॉइंट की दी हुई HTTP स्थिति दिखाता है।
• सक्रिय स्विच एक एंडपॉइंट को रोक देता है। इसके बंद रहने के दौरान होने वाले इवेंट बाद में नहीं भेजे जाते।
• हटाएं एंडपॉइंट और इसका सीक्रेट मिटा देता है।

सामान्य सवाल

इंटीग्रेशन के तहत Zapier, Make और n8n ऐप से यह कैसे अलग है? वे कनेक्शन इंटीग्रेशन पेज और इसके छह इवेंट टाइप इस्तेमाल करते हैं। इनकी बॉडी {"event", "workspace", "sent_at", "data"} है, और जब आप एक सीक्रेट सेट करते हैं तो सिग्नेचर हेडर X-Ringhum-Signature: sha256=… होता है, सिर्फ़ बॉडी का एक HMAC-SHA256। यहां बताए गए डेवलपर वेबहुक ज़्यादा इवेंट कवर करते हैं और टाइमस्टैंप के साथ v1= सिग्नेचर इस्तेमाल करते हैं। देखें क्या भेजा जाए यह चुनना।

मेरा एंडपॉइंट 2xx लौटाता है लेकिन मेरे कोड को कुछ नहीं दिखता। जांचें कि उस एंडपॉइंट के लिए इवेंट टिक है, एंडपॉइंट सक्रिय है, और आपका फ़ायरवॉल इंटरनेट से रिक्वेस्ट की अनुमति देता है।

सिग्नेचर जांच क्यों फेल होती है? ज़्यादातर बार बॉडी को हैश करने से पहले पार्स और फिर से एनकोड किया गया था। कच्चे बाइट्स को बिल्कुल वैसे ही हैश करें जैसे प्राप्त हुए। </content>