ವೆಬ್‌ಹುಕ್‌ಗಳ ಅವಲೋಕನ

ThunderPhone ನೈಜ-ಸಮಯದ ಈವೆಂಟ್‌ಗಳನ್ನು ಹೇಗೆ ತಲುಪಿಸುತ್ತದೆ, ಸಹಿಗಳನ್ನು ಹೇಗೆ ಪರಿಶೀಲಿಸುವುದು ಮತ್ತು ಲೆಗಸಿ ಹಾಗೂ ಎಂಡ್‌ಪಾಯಿಂಟ್-ಆಧಾರಿತ ವಿತರಣಾ ಮಾದರಿಗಳನ್ನು ಹೇಗೆ ಹೋಲಿಸಬಹುದು ಎಂಬುದು.

ThunderPhone ಕರೆ ಸಮಯದಲ್ಲಿ ಘಟನೆಗಳು ಸಂಭವಿಸಿದಾಗ ನಿಮ್ಮ ಸರ್ವರ್‌ಗೆ HTTP POST ವಿನಂತಿಗಳನ್ನು ಕಳುಹಿಸುತ್ತದೆ — ಒಳಬರುವ ಕರೆ ಆರಂಭವಾದಾಗ, ಕರೆ ಮುಗಿದಾಗ, ಗ್ರೇಡಿಂಗ್ ರನ್ ಪೂರ್ಣಗೊಂಡಾಗ, ಎಚ್ಚರಿಕೆ ಸಕ್ರಿಯಗೊಂಡಾಗ ಮತ್ತು ಇತ್ಯಾದಿ. ಎರಡು ವಿತರಣಾ ಮಾದರಿಗಳಿವೆ:

ಈವೆಂಟ್‌ಗಳ ಕ್ಯಾಟಲಾಗ್ ನಲ್ಲಿ ಪಟ್ಟಿ ಮಾಡಲಾದ ಎಲ್ಲಾ ಈವೆಂಟ್ ಪ್ರಕಾರಗಳನ್ನು ವೆಬ್‌ಹುಕ್ ಎಂಡ್‌ಪಾಯಿಂಟ್‌ಗಳ ಮೂಲಕ ವಿತರಿಸಲಾಗುತ್ತದೆ. ಆರು ಕರೆ-ಜೀವನಚಕ್ರದ ಈವೆಂಟ್‌ಗಳು (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) ಹಳೆಯ ಏಕ-URL ವೆಬ್‌ಹುಕ್‌ಗೆ ಸಹ ಕಳುಹಿಸಲಾಗುತ್ತವೆ — ನೀವು ಹಳೆಯ URL ಮತ್ತು ಹೊಂದಾಣಿಕೆಯಾಗುವ ಎಂಡ್‌ಪಾಯಿಂಟ್ ಎರಡನ್ನೂ ಹೊಂದಿದ್ದರೆ, ನೀವು ಈವೆಂಟ್ ಅನ್ನು ಎರಡೂ ಮಾರ್ಗಗಳಲ್ಲಿ ಪಡೆಯುತ್ತೀರಿ. ತಡೆಹಿಡಿಯುವ ವರ್ತನೆ (telephony.incoming / web.incoming ಕಾನ್ಫಿಗರೇಶನ್ ವಿನಿಮಯ ಮತ್ತು ವೆಬ್‌ಹುಕ್-ಮೋಡ್‌ನ ಟೂಲ್ ಡಿಸ್ಪ್ಯಾಚ್) ಹಳೆಯ ಮಾರ್ಗದಲ್ಲಿ ಮಾತ್ರ ಇರುತ್ತದೆ; ಪ್ರತಿ ಎಂಡ್‌ಪಾಯಿಂಟ್ ವಿತರಣೆಯು ಪ್ರತಿಕ್ರಿಯೆಗಾಗಿ ಕಾಯದ ಅಧಿಸೂಚನೆಯಾಗಿದೆ.

ಪೇಲೋಡ್ ಸ್ವರೂಪ#

ಎಂಡ್‌ಪಾಯಿಂಟ್ ವಿತರಣೆಗಳು data, event_id, ಮತ್ತು type ಹೊಂದಿರುವ JSON ಆಬ್ಜೆಕ್ಟ್ ಆಗಿರುತ್ತವೆ:

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

event_id ಪ್ರತಿ ಹೊರಸೂಸಲಾದ ಈವೆಂಟ್‌ಗೆ ಅನನ್ಯವಾಗಿರುತ್ತದೆ. ಇದು ಮರುಪ್ರಯತ್ನಗಳಾದ್ಯಂತ ಮತ್ತು ಈವೆಂಟ್ ಪಡೆಯುವ ಪ್ರತಿಯೊಂದು ಎಂಡ್‌ಪಾಯಿಂಟ್‌ನಲ್ಲೂ ಒಂದೇ ಆಗಿರುತ್ತದೆ — ಇದರ ಆಧಾರದ ಮೇಲೆ ಡೀಡಪ್ ಮಾಡಿ.

ಹಳೆಯ ಏಕ-URL ವೆಬ್‌ಹುಕ್ ಅದೇ type ಮತ್ತು data ಅನ್ನು ಕಳುಹಿಸುತ್ತದೆ, ಆದರೆ event_id ಇಲ್ಲದೆ:

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

ಸಂವಹನದಲ್ಲಿ, ಪ್ರತಿಯೊಂದು ಬಾಡಿಯನ್ನೂ ಕ್ಯಾನಾನಿಕಲ್ ರೀತಿಯಲ್ಲಿ ಸೀರಿಯಲೈಸ್ ಮಾಡಲಾಗುತ್ತದೆ — ಕೀಗಳನ್ನು ಅಕಾರಾದಿ ಕ್ರಮದಲ್ಲಿ ವಿಂಗಡಿಸಲಾಗುತ್ತದೆ, ವೈಟ್‌ಸ್ಪೇಸ್ ಇರುವುದಿಲ್ಲ, UTF-8 ಬಳಸಲಾಗುತ್ತದೆ. ಈ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳಲ್ಲಿನ ಸುಂದರವಾಗಿ ಮುದ್ರಿಸಲಾದ ಉದಾಹರಣೆಗಳು ಓದಲು ಸುಲಭವಾಗಲು ಮಾತ್ರ ಇವೆ.

ಈವೆಂಟ್ ಪ್ರಕಾರಗಳು ಮತ್ತು ಪೇಲೋಡ್ ಫೀಲ್ಡ್‌ಗಳ ಸಂಪೂರ್ಣ ಪಟ್ಟಿಗಾಗಿ ಈವೆಂಟ್‌ಗಳ ಕ್ಯಾಟಲಾಗ್ ನೋಡಿ.

ಸಹಿ ಪರಿಶೀಲನೆ#

ಪ್ರತಿಯೊಂದು ವಿನಂತಿಯು ಎರಡು ಸಹಿಗಳನ್ನು ಹೊಂದಿರುತ್ತದೆ, ಎರಡೂ ಎಂಡ್‌ಪಾಯಿಂಟ್‌ನ secret (ಅಥವಾ ಹಳೆಯ ವಿತರಣೆಗಳಿಗಾಗಿ ನಿಮ್ಮ ಸಂಸ್ಥೆ-ಮಟ್ಟದ ವೆಬ್‌ಹುಕ್ secret) ಅನ್ನು ಕೀಲಿಯಾಗಿ ಬಳಸುವ HMAC-SHA256 ಸಹಿಗಳಾಗಿವೆ:

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> ಸಮಯಮುದ್ರೆ, ವಿಧಾನ, ಪಥ ಮತ್ತು ಕ್ವೆರಿ ಹಾಗೂ ಕಚ್ಚಾ ಬಾಡಿಗೆ ಸಹಿ ಮಾಡುತ್ತದೆ. ಇದನ್ನು ಪರಿಶೀಲಿಸಿ ಮತ್ತು ಸೆರೆಹಿಡಿದ ವಿನಂತಿಯನ್ನು ನಂತರ ಮರುಚಲಾಯಿಸಲು ಸಾಧ್ಯವಾಗದಂತೆ, ನಿಮ್ಮ ಗಡಿಯಾರದ ಸಮಯದಿಂದ t 5 ನಿಮಿಷಗಳಿಗಿಂತ ಹೆಚ್ಚು ದೂರವಿರುವ ವಿನಂತಿಗಳನ್ನು ತಿರಸ್ಕರಿಸಿ. ಮರುಪ್ರಯತ್ನಗಳನ್ನು ಕಳುಹಿಸುವಾಗ ಅವುಗಳಿಗೆ ಮತ್ತೆ ಸಹಿ ಮಾಡಲಾಗುತ್ತದೆ.
• X-ThunderPhone-Signature ಕೇವಲ ಕಚ್ಚಾ ಬಾಡಿಗೆ ಸಹಿ ಮಾಡುತ್ತದೆ. ಅಸ್ತಿತ್ವದಲ್ಲಿರುವ ಪರಿಶೀಲಕಗಳು ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತಿರಲು, ಇದನ್ನು ಬದಲಾಯಿಸದೆ ಇನ್ನೂ ಕಳುಹಿಸಲಾಗುತ್ತದೆ.

ಹಂತಗಳು#

1. ಯಾವುದೇ ಪಾರ್ಸಿಂಗ್‌ಗಿಂತ ಮೊದಲು ಹೆಡರ್, ಮೆತಡ್, ಕಚ್ಚಾ ಪಾತ್ ಮತ್ತು ಕ್ವೆರಿ, ಹಾಗೂ ಕಚ್ಚಾ ಬಾಡಿಯನ್ನು ಓದಿ.
2. ನಿಮ್ಮ ಸೀಕ್ರೆಟ್‌ನೊಂದಿಗೆ <t>\n<METHOD>\n<path and query>\n<body> ನ ಹೆಕ್ಸ್ HMAC-SHA256 ಅನ್ನು ಲೆಕ್ಕಹಾಕಿ.
3. t 300 ಸೆಕೆಂಡುಗಳಿಗಿಂತ ಹೆಚ್ಚು ವ್ಯತ್ಯಾಸವಾಗಿದ್ದರೆ ಅಥವಾ ಫಲಿತಾಂಶವು ಸ್ಥಿರ-ಸಮಯದ ಹೋಲಿಕೆಯಲ್ಲಿ v1 ಗೆ ಹೊಂದಿಕೆಯಾಗದಿದ್ದರೆ ವಿನಂತಿಯನ್ನು ತಿರಸ್ಕರಿಸಿ.

ಬಾಡಿಗಳು ಕ್ಯಾನನಿಕಲ್ JSON ಸೀರಿಯಲೈಸೇಶನ್‌ಗಳಾಗಿವೆ (ವಿಂಗಡಿಸಿದ ಕೀಗಳು, ಸಂಕ್ಷಿಪ್ತ ವಿಭಜಕಗಳು), ಮತ್ತು ನಾವು ರವಾನಿಸುವ ನಿಖರವಾದ ಬೈಟ್‌ಗಳಿಗೇ ಸಹಿ ಮಾಡುತ್ತೇವೆ. ಪರಿಶೀಲನೆ ಮಾರ್ಗದರ್ಶಿ ಯಲ್ಲಿ ನಿಖರವಾದ ಸಹಿ ಮಾಡಿದ ಸ್ಟ್ರಿಂಗ್, ಕಾರ್ಯನಿರ್ವಹಿತ ಉದಾಹರಣೆ, SDK ಇಲ್ಲದ ಕೋಡ್ ಮತ್ತು ಲೆಗಸಿ ಹೆಡರ್ ಇವೆ.

from flask import Flask, abort, request
from thunderphone import verify_signature
 
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);

ವಿತರಣಾ ಅರ್ಥವ್ಯವಸ್ಥೆ#

ಈ ಅರ್ಥವ್ಯವಸ್ಥೆಗಳು ಎಂಡ್‌ಪಾಯಿಂಟ್ ವಿತರಣೆಗಳಿಗೆ ಅನ್ವಯಿಸುತ್ತವೆ. ಹಳೆಯ ಏಕ-URL ವೆಬ್‌ಹುಕ್ ಮರುಪ್ರಯತ್ನಗಳಿಲ್ಲದ ಏಕ ಸಿಂಕ್ರೋನಸ್ ಪ್ರಯತ್ನವಾಗಿದೆ; ಫೋನ್-ಕರೆ telephony.incoming ಕಾನ್ಫಿಗರೇಶನ್ ವಿನಿಮಯಕ್ಕೆ ಮಾತ್ರ ವಿನಾಯಿತಿ ಇದೆ, ಇದನ್ನು ಒಮ್ಮೆ ಮರುಪ್ರಯತ್ನಿಸಲಾಗುತ್ತದೆ.

ಹಳೆಯ ಮತ್ತು ಎಂಡ್‌ಪಾಯಿಂಟ್-ಆಧಾರಿತ ವೆಬ್‌ಹುಕ್‌ಗಳ ನಡುವೆ ಆಯ್ಕೆ ಮಾಡುವುದು#

ಹೊಸ ಏಕೀಕರಣಗಳು ಎಂಡ್‌ಪಾಯಿಂಟ್-ಆಧಾರಿತ ವೆಬ್‌ಹುಕ್‌ಗಳ ಮೂಲಕ ಈವೆಂಟ್‌ಗಳನ್ನು ಬಳಸಬೇಕು. ಕರೆ ಸ್ವೀಕರಿಸುವ ಸಮಯದಲ್ಲಿ ಕರೆಗಳನ್ನು ಡೈನಾಮಿಕ್ ಆಗಿ ಕಾನ್ಫಿಗರ್ ಮಾಡುವಾಗ ಅಥವಾ ವೆಬ್‌ಹುಕ್-ಮೋಡ್ ಟೂಲ್ ಡಿಸ್ಪ್ಯಾಚ್ ಬಳಸುವಾಗ ಮಾತ್ರ ಹಳೆಯ URL ಅನ್ನು ಉಳಿಸಿಕೊಳ್ಳಿ (ಅಥವಾ ಸೇರಿಸಿ) — ಆ ವಿನಂತಿ/ಪ್ರತಿಕ್ರಿಯೆ ವಿನಿಮಯಗಳು ಹಳೆಯ ಮಾರ್ಗದಲ್ಲಿ ಮಾತ್ರ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ.

ಸಂಬಂಧಿತ#