---
title: "वेबहुक्सचा आढावा"
description: "ThunderPhone रिअल-टाइम इव्हेंट्स कसे वितरित करते, स्वाक्षऱ्या कशा पडताळायच्या आणि लेगसी व एंडपॉइंट-आधारित वितरण मॉडेल्सची तुलना कशी होते."
---

ThunderPhone कॉलदरम्यान घटना घडल्यावर तुमच्या सर्व्हरला HTTP `POST` विनंत्या पाठवते — इनबाउंड कॉल सुरू होतो, कॉल संपतो, ग्रेडिंग रन पूर्ण होते, अलर्ट ट्रिगर होतो इत्यादी. **दोन वितरण मॉडेल्स** आहेत:

<CardGroup cols={2}>
  <Card title="Webhook एंडपॉइंट्स (शिफारस केलेले)" icon="bolt" href="/mr/webhooks/endpoints">
    अनेक URLs, प्रत्येक एंडपॉइंटसाठी स्वतंत्र सीक्रेट्स, प्रत्येक एंडपॉइंटसाठी इव्हेंट फिल्टर्स,
    आणि स्वयंचलित पुनर्प्रयत्न.
    `GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints` द्वारे व्यवस्थापित करा.
  </Card>
  <Card title="सिंगल-URL लेगसी webhook" icon="link" href="/api-reference/organizations#legacy-single-url-webhook">
    प्रत्येक ऑर्गसाठी एक URL. **अवरोधक** कॉन्फिगरेशन एक्सचेंजेससह
    कॉल-लाइफसायकल इव्हेंट्स समाविष्ट करतो. `GET/PUT /v1/webhook` येथे व्यवस्थापित केला जातो.
  </Card>
</CardGroup>

[इव्हेंट्स कॅटलॉग](/mr/webhooks/events) मधील सर्व दहा इव्हेंट प्रकार webhook एंडपॉइंट्सद्वारे
वितरित केले जातात. सहा कॉल-लाइफसायकल इव्हेंट्स
(`telephony.incoming`, `telephony.complete`, `telephony.tool`,
`web.incoming`, `web.complete`, `web.tool`) **तसेच** लेगसी सिंगल-URL
webhook वर पाठवले जातात — तुमच्याकडे लेगसी URL आणि जुळणारा एंडपॉइंट दोन्ही असल्यास,
तुम्हाला इव्हेंट **दोन्ही** मार्गांवर प्राप्त होतो. अवरोधक वर्तन
([`telephony.incoming` / `web.incoming` कॉन्फिगरेशन
एक्सचेंज](/mr/webhooks/call-incoming) आणि webhook-मोड
[टूल डिस्पॅच](/mr/tools/overview)) केवळ लेगसी मार्गावर असते;
प्रत्येक एंडपॉइंट वितरण फायर-अँड-फॉरगेट सूचना असते.

## पेलोड स्वरूप

एंडपॉइंट वितरणांमध्ये `data`, `event_id`, आणि `type` असलेला JSON ऑब्जेक्ट असतो:

```json
{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}
```

`event_id` प्रत्येक उत्सर्जित इव्हेंटसाठी अद्वितीय असतो. तो पुनर्प्रयत्नांमध्ये
**आणि** इव्हेंट प्राप्त करणाऱ्या प्रत्येक एंडपॉइंटमध्ये समान असतो — त्यावर डिडुप्लिकेशन करा.

लेगसी सिंगल-URL webhook तोच `type` आणि `data` पाठवतो, पण
`event_id` **विना**:

```json
{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}
```

वायरवर, प्रत्येक बॉडी कॅनॉनिकली सिरिअलाइझ केली जाते — कीज वर्णानुक्रमाने क्रमबद्ध,
व्हाइटस्पेस नाही, UTF-8. या दस्तऐवजांमधील प्रीटी-प्रिंट केलेली उदाहरणे
केवळ वाचनीयतेसाठी आहेत.

इव्हेंट प्रकारांची आणि पेलोड फील्ड्सची संपूर्ण यादी पाहण्यासाठी
[इव्हेंट्स कॅटलॉग](/mr/webhooks/events) पहा.

## स्वाक्षरी पडताळणी

प्रत्येक विनंतीमध्ये `X-ThunderPhone-Signature` हेडरमध्ये **कच्च्या विनंतीच्या
बॉडीवर** HMAC-SHA256 स्वाक्षरी असते. स्वाक्षरी की म्हणजे एंडपॉइंटचा
`secret` (किंवा लेगसी डिलिव्हरींसाठी तुमच्या संस्थास्तरीय वेबहुकचा
`secret`) आहे.

### पायऱ्या

1. कोणतेही पार्सिंग करण्यापूर्वी कच्ची विनंती बॉडी वाचा.
2. `hmac_sha256(secret, body).hexdigest()` ची गणना करा.
3. `X-ThunderPhone-Signature` हेडरशी स्थिर वेळेत तुलना करा.

आम्ही प्रसारित केलेल्या नेमक्या बाइट्सवर स्वाक्षरी करतो आणि ते बाइट्स
कॅनॉनिकल JSON सिरीयलायझेशनचे असतात (क्रमबद्ध की, कॉम्पॅक्ट विभाजक). त्यामुळे
कच्च्या बॉडीवर पडताळणी नेहमी कार्य करते — आणि तुमचे फ्रेमवर्क तुम्हाला
फक्त पार्स केलेला JSON देत असल्यास, तो क्रमबद्ध की आणि कॉम्पॅक्ट विभाजकांसह
पुन्हा सिरीयलाइज केल्यास एकसारखे बाइट्स तयार होतात. दोन्ही पद्धती
[पडताळणी मार्गदर्शिकेत](/mr/guides/verify-webhook-signatures) समाविष्ट आहेत.

<CodeGroup>
```python Python
import hmac
import hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature or "")

# Example Flask handler
from flask import Flask, request, abort
app = Flask(__name__)

@app.post("/thunderphone-webhook")
def handle():
    body = request.get_data()
    sig = request.headers.get("X-ThunderPhone-Signature", "")
    if not verify_signature(body, sig, WEBHOOK_SECRET):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204
```

```javascript Node.js (Express)
import crypto from "node:crypto";
import express from "express";

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (!signature || expected.length !== signature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.header("X-ThunderPhone-Signature") || "";
    if (!verifySignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);
```
</CodeGroup>

## डिलिव्हरी अर्थविषयक नियम

हे नियम **एंडपॉइंट** डिलिव्हरींना लागू होतात. जुन्या एकल-URL
वेबहुकमध्ये पुन्हा प्रयत्नांशिवाय एकच समकालिक प्रयत्न असतो.

<AccordionGroup>
  <Accordion title="पुन्हा प्रयत्न">
    प्रत्येक इव्हेंटचा लगेच एकदा प्रयत्न केला जातो. कोणताही `2xx` प्रतिसाद
    डिलिव्हरीची पावती देतो. इतर कोणताही परिणाम झाल्यास (non-2xx,
    कनेक्शन त्रुटी, टाइमआउट), आम्ही **पहिल्या प्रयत्नानंतर 1 मिनिट, 5 मिनिटे, 30 मिनिटे, 2 तास, 6 तास,
    12 तास आणि 24 तासांनी** पुन्हा प्रयत्न करतो — 24 तासांमध्ये पसरलेले
    8 प्रयत्न. प्रत्येक प्रयत्न अयशस्वी झाल्यास, डिलिव्हरी थांबते आणि एंडपॉइंटला
    [वेबहुक एंडपॉइंट्स](/mr/webhooks/endpoints) मध्ये
    `status="failing"` म्हणून चिन्हांकित केले जाते. पेलोड टिकाऊपणे स्वीकारला
    जाताच `2xx` परत करा; प्रक्रिया असमकालिकपणे करा.
  </Accordion>

  <Accordion title="क्रमवारी">
    डिलिव्हरीची क्रमवारी सर्वोत्तम-प्रयत्न तत्त्वावर असते. प्रत्यक्षात, इव्हेंट
    जारी होतात त्या क्रमाने आम्ही ते डिलिव्हर करतो, परंतु अयशस्वी झाल्यास
    पुन्हा प्रयत्नांमुळे क्रम बदलू शकतो. नेहमी डुप्लिकेट काढून टाका आणि
    `call_id` / ऑब्जेक्ट आयडी नुसार समेट करा.
  </Accordion>

  <Accordion title="डुप्लिकेट">
    डिलिव्हरी **किमान-एकदा** असते: आम्हाला न मिळालेल्या प्रतिसादानंतरचा
    पुन्हा प्रयत्न एखादा इव्हेंट डुप्लिकेट करू शकतो. प्रत्येक पुन्हा प्रयत्नात
    तोच `event_id` असतो, त्यामुळे प्रक्रिया केलेले आयडी संग्रहित करा आणि
    पुनरावृत्ती वगळा. `event_id` एंडपॉइंट्समध्येही सामायिक असतो — त्याच
    इव्हेंटसाठी सदस्यता घेतलेल्या दोन एंडपॉइंट्सना तोच `event_id` मिळतो.
  </Accordion>

  <Accordion title="टाइमआउट">
    एंडपॉइंट डिलिव्हरींमध्ये प्रत्येक प्रयत्नासाठी **30 सेकंदांचा** टाइमआउट असतो. जुन्या मार्गावर,
    थेट कॉलचे वर्तन नियंत्रित करणाऱ्या ब्लॉकिंग विनंत्या — 
    [`telephony.incoming` / `web.incoming`](/mr/webhooks/call-incoming)
    कॉन्फिगरेशन देवाणघेवाण — **10 सेकंदांनंतर** टाइमआउट होतात, परंतु धीमा
    प्रतिसाद कॉल उचलण्यास विलंब करतो, त्यामुळे काही सेकंदांत उत्तर देण्याचा
    प्रयत्न करा. वेबहुक-मोड [टूल डिस्पॅच](/mr/tools/overview) मध्ये डीफॉल्टनुसार
    20 सेकंद उपलब्ध असतात आणि टूल घोषणांमध्ये शीर्ष-स्तरीय `timeout` सेट केला जाऊ शकतो.
  </Accordion>

  <Accordion title="स्रोत IP">
    आउटबाउंड वेबहुक ThunderPhone च्या क्लाउड IP श्रेणीतून येतात.
    तुमच्या फायरवॉलला अनुमत यादी आवश्यक असल्यास, सपोर्टशी संपर्क साधा आणि आम्ही
    सध्याच्या श्रेणी सामायिक करू.
  </Accordion>
</AccordionGroup>

## जुने आणि एंडपॉइंट-आधारित वेबहुक यांपैकी निवड

| वैशिष्ट्य | जुने (`/v1/webhook`) | एंडपॉइंट्स (`/v1/developer/webhook-endpoints`) |
|---------|------------------------|----------------------------------------------|
| URL ची संख्या | प्रत्येक संस्थेसाठी 1 | प्रत्येक संस्थेसाठी अनेक |
| इव्हेंट व्याप्ती | फक्त `telephony.*` / `web.*` | सर्व 10 इव्हेंट प्रकार |
| इव्हेंट फिल्टर | — | प्रत्येक एंडपॉइंटनुसार |
| पुन्हा प्रयत्न | नाही | 24 तासांत 8 प्रयत्न |
| एन्व्हलप | `type` + `data` | `type` + `data` + `event_id` |
| सिक्रेट रोटेशन | एकमेव सिक्रेट बदलते | प्रत्येक एंडपॉइंटसाठी सिक्रेट |
| हटविल्याशिवाय निष्क्रिय करणे | `{"url": ""}` सह `PUT /v1/webhook` | `status=disabled` |
| स्टेटस दृश्यमानता | — | `active` / `disabled` / `failing` |
| ब्लॉकिंग कॉन्फिगरेशन देवाणघेवाण | होय ([`telephony.incoming` / `web.incoming`](/mr/webhooks/call-incoming)) | कधीही नाही — फक्त सूचना |
| यासाठी सर्वोत्तम | डायनॅमिक कॉल कॉन्फिगरेशन | प्रॉडक्शनमधील इव्हेंट वापर |

नवीन इंटिग्रेशननी एंडपॉइंट-आधारित वेबहुकद्वारे इव्हेंट वापरावेत.
तुम्ही कॉल उचलण्याच्या वेळी कॉल डायनॅमिकपणे कॉन्फिगर करत असाल किंवा
वेबहुक-मोड टूल डिस्पॅच वापरत असाल तरच जुना URL ठेवा (किंवा जोडा) — त्या
विनंती/प्रतिसाद देवाणघेवाणी फक्त जुन्या मार्गावर चालतात.

---

## संबंधित

<CardGroup cols={2}>
  <Card title="इव्हेंट कॅटलॉग" icon="list" href="/mr/webhooks/events">
    सर्व इव्हेंट प्रकार आणि त्यांचे पेलोड.
  </Card>
  <Card title="वेबहुक एंडपॉइंट्स" icon="bolt" href="/mr/webhooks/endpoints">
    अनेक एंडपॉइंट्स, इव्हेंट फिल्टर्स आणि सिक्रेट्स व्यवस्थापित करा.
  </Card>
  <Card title="telephony.incoming / web.incoming" icon="phone" href="/mr/webhooks/call-incoming">
    कॉल कॉन्फिगर करण्यासाठी तुमच्या सर्व्हरने उत्तर द्यावी लागणारी ब्लॉकिंग विनंती.
  </Card>
  <Card title="telephony.complete / web.complete" icon="phone" href="/mr/webhooks/call-complete">
    ट्रान्स्क्रिप्ट, रेकॉर्डिंग आणि मेट्रिक्ससह कॉलनंतरचा पेलोड.
  </Card>
</CardGroup>