डेवलपर दस्तावेज़

क्विकस्टार्ट

चार चरणों में API key बनाएं, पहली request भेजें और webhooks सुरक्षित रूप से प्राप्त करें।

1. API key बनाएं

अकाउंट कंसोल में एक कनेक्शन बनाएं और API key जारी करें। पूरी key सिर्फ़ एक बार दिखती है, इसलिए उसे secret manager में सुरक्षित रखें।

अकाउंट → API & Webhooks में अपने पर्सनल workspace या अपने स्वामित्व वाले teamspace के लिए कनेक्शन बनाएं।
ज़रूरी अनुमति-क्षेत्र चुनें: notes:read, transcripts:read, summaries:read, webhooks:manage.
key alt_live_{key_id}.{secret} जैसी दिखती है और सिर्फ़ एक बार दिखाई जाती है। इसे secret manager में रखें।

नीचे दी गई हर कमांड जस की तस चले, इसके लिए key को अपने शेल में export करें:

shell

export ALT_API_KEY="alt_live_...paste-your-key-here..."

2. मौजूदा नोट्स प्राप्त करें

पूरी सूची में आगे बढ़ने के लिए API से मिला cursor अगली request में भेजें। फिर हर नोट का ट्रांसक्रिप्ट और सारांश प्राप्त करें।

curl

curl 'https://public-api.altalt.io/v1/notes?limit=100' \
  -H "Authorization: Bearer $ALT_API_KEY"

# Follow next_cursor until has_more is false
curl 'https://public-api.altalt.io/v1/notes?limit=100&cursor=NEXT_CURSOR' \
  -H "Authorization: Bearer $ALT_API_KEY"

# Fetch content per note (scopes: transcripts:read / summaries:read)
curl 'https://public-api.altalt.io/v1/notes/NOTE_ID/transcript' \
  -H "Authorization: Bearer $ALT_API_KEY"
curl 'https://public-api.altalt.io/v1/notes/NOTE_ID/summary' \
  -H "Authorization: Bearer $ALT_API_KEY"

इसके बाद incremental sync के लिए ?updated_after=<last sync time> से poll करें या webhooks पर भरोसा करें।

3. webhook endpoint रजिस्टर करें

polling के बजाय नए और बदले हुए नोट्स की सूचना पाने के लिए एक पब्लिक HTTPS endpoint रजिस्टर करें।

curl

curl -X POST 'https://public-api.altalt.io/v1/webhook-endpoints' \
  -H "Authorization: Bearer $ALT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhooks/alt",
    "events": ["note.ended", "note.summary.generated", "note.updated", "note.deleted"]
  }'

रिस्पॉन्स में signing_secret (whsec_...) शामिल होता है — यह सिर्फ़ एक बार दिखता है। endpoint pending_verification स्थिति में शुरू होता है; जब आपका receiver verification इवेंट का जवाब 2xx से देता है, तब यह active हो जाता है। यही काम बिना कोड लिखे कंसोल से भी किया जा सकता है।

4. webhook सिग्नेचर वेरिफ़ाई करें

हर webhook request का Standard Webhooks सिग्नेचर जांचकर पुष्टि करें कि वह Alt से आई है। event_id से डुप्लिकेट छोड़ें, पहले response दें और फिर REST API से नया कंटेंट प्राप्त करें।

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";
import http from "node:http";

// whsec_... secret from endpoint creation (shown once). Keep it server-side.
const SECRET = process.env.ALT_WEBHOOK_SECRET;
const secretBytes = Buffer.from(SECRET.slice("whsec_".length), "base64url");

const TOLERANCE_SECONDS = 300;

function isValidSignature(headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatureHeader = headers["webhook-signature"];
  if (!id || !timestamp || !signatureHeader) return false;

  // Reject stale timestamps (replay protection)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secretBytes)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest("base64");

  // Header may contain multiple space-delimited signatures: "v1,abc v1,def"
  return String(signatureHeader)
    .split(" ")
    .some((part) => {
      const [version, signature] = part.split(",");
      if (version !== "v1" || !signature) return false;
      const a = Buffer.from(signature);
      const b = Buffer.from(expected);
      return a.length === b.length && timingSafeEqual(a, b);
    });
}

http
  .createServer((req, res) => {
    if (req.method !== "POST" || req.url !== "/webhooks/alt") {
      res.writeHead(404).end();
      return;
    }
    let rawBody = "";
    req.on("data", (chunk) => (rawBody += chunk));
    req.on("end", () => {
      if (!isValidSignature(req.headers, rawBody)) {
        res.writeHead(401).end();
        return;
      }
      const event = JSON.parse(rawBody);
      // 1. Dedupe on event.event_id (deliveries are at-least-once).
      // 2. Enqueue for async processing, then ack fast.
      // 3. Fetch the note from the REST API; apply only if revision is newer.
      console.log(event.event_type, event.data.note_id, event.data.revision);
      res.writeHead(204).end();
    });
  })
  .listen(3000);

Python

import base64, hashlib, hmac, json, os, time
from http.server import BaseHTTPRequestHandler, HTTPServer

# whsec_... secret from endpoint creation (shown once). Keep it server-side.
raw_secret = os.environ["ALT_WEBHOOK_SECRET"].removeprefix("whsec_")
SECRET = base64.urlsafe_b64decode(raw_secret + "=" * (-len(raw_secret) % 4))

TOLERANCE_SECONDS = 300


def is_valid_signature(headers, raw_body: bytes) -> bool:
    msg_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    signature_header = headers.get("webhook-signature", "")
    if not msg_id or not timestamp or not signature_header:
        return False

    # Reject stale timestamps (replay protection)
    if abs(time.time() - float(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed_content = f"{msg_id}.{timestamp}.".encode() + raw_body
    digest = hmac.new(SECRET, signed_content, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode()

    # Header may contain multiple space-delimited signatures: "v1,abc v1,def"
    for part in signature_header.split(" "):
        version, _, signature = part.partition(",")
        if version == "v1" and signature and hmac.compare_digest(signature, expected):
            return True
    return False


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/webhooks/alt":
            self.send_response(404); self.end_headers(); return
        raw_body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        if not is_valid_signature(self.headers, raw_body):
            self.send_response(401); self.end_headers(); return
        event = json.loads(raw_body)
        # 1. Dedupe on event["event_id"] (deliveries are at-least-once).
        # 2. Enqueue for async processing, then ack fast.
        # 3. Fetch the note from the REST API; apply only if revision is newer.
        print(event["event_type"], event["data"]["note_id"], event["data"]["revision"])
        self.send_response(204); self.end_headers()


HTTPServer(("", 3000), Handler).serve_forever()

सिग्नेचर Standard Webhooks स्पेसिफ़िकेशन के अनुसार बनते हैं, इसलिए आधिकारिक standardwebhooks लाइब्रेरी (npm / PyPI) इस्तेमाल की जा सकती हैं। डुप्लिकेट इवेंट, delivery का क्रम और छूटे बदलाव संभालने के लिए Webhooks देखें।