Documentación para desarrolladores

Inicio rápido

Cree una clave de API, envíe su primera solicitud y reciba webhooks de forma segura en cuatro pasos.

1. Cree una clave de API

Cree una integración y emita una clave desde la consola de su cuenta. La clave completa se muestra una sola vez: guárdela en un gestor de secretos.

Cuenta → API & Webhooks: cree una integración para su espacio de trabajo personal o para un teamspace del que sea propietario.
Elija los permisos necesarios: notes:read, transcripts:read, summaries:read, webhooks:manage.
La clave tiene el formato alt_live_{key_id}.{secret} y se muestra una sola vez. Guárdela en un gestor de secretos.

Expórtela en su shell para que todos los comandos siguientes funcionen tal cual:

shell

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

2. Obtenga las notas existentes

Envíe el cursor devuelto por la API en la solicitud siguiente para recorrer toda la lista. Después, obtenga la transcripción y el resumen de cada nota.

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"

Para la sincronización incremental posterior, haga polling con ?updated_after=<last sync time> o apóyese en los webhooks.

3. Registre un endpoint de webhook

Registre un endpoint HTTPS público para recibir avisos de notas nuevas y modificadas en lugar de hacer polling.

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"]
  }'

La respuesta incluye el signing_secret (whsec_...), que se muestra una sola vez. El endpoint empieza en estado pending_verification y se activa cuando su receptor responde al evento de verificación con un 2xx. También puede hacerlo sin escribir código desde la consola.

4. Verifique las firmas de los webhooks

Verifique la firma Standard Webhooks de cada solicitud para confirmar que proviene de Alt. Omita duplicados mediante event_id, responda primero y obtenga después el contenido actualizado desde la 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()

Las firmas siguen la especificación Standard Webhooks, por lo que puede usar las bibliotecas oficiales standardwebhooks (npm / PyPI). Consulte Webhooks para gestionar duplicados, el orden de entrega y los cambios omitidos.