Auf dieser Seite
callmetra.Dokumentation
Workspace ↗
Dokumentationsnavigation
callmetra./Dokumentation/API-Schlüssel und Webhooks

Entwickler

API-Schlüssel und Webhooks

Lesender API-Zugriff, eigene Anrufereignisse und signierte Zustellungen.

Aktualisiert

Lesenden Schlüssel erstellen

Als Organisationsadmin öffnest du Einstellungen → API & Automationen. Der Zugriff benötigt einen passenden Tarif, etwa Team. Erstelle einen Schlüssel nur mit den benötigten Ressourcen-Rechten. Kopiere das Geheimnis einmalig und speichere es außerhalb der Versionsverwaltung. Schlüssel laufen nach 30 Tagen ab und erben die aktuellen Rechte des Besitzers. Widerrufe ungenutzte Schlüssel.

API-Einstellungen der öffentlichen Demo ohne neu erstellten oder sichtbaren Schlüssel.
API-Einstellungen der öffentlichen Demo ohne neu erstellten oder sichtbaren Schlüssel.

API-Einstellungen der öffentlichen Demo ohne neu erstellten oder sichtbaren Schlüssel.

Der öffentliche REST-Vertrag bietet GET-Ressourcen unter /api/v1: calls, statistics, employees, teams, dashboards, integrations und organization. Jede Ressource verlangt ihren passenden Lese-Scope, etwa calls:read. Die Identität legt die Organisation fest; Anfragen können keinen anderen Mandanten auswählen. Rufnummern sind maskiert. Exakte Filter und Antworten stehen in der OpenAPI-Referenz.

Anfrage senden

Setze CALLMETRA_ORIGIN in deiner Umgebung auf deinen tatsächlichen HTTPS-Ursprung und CALLMETRA_API_KEY auf deinen Schlüssel. Füge keinen echten Schlüssel in dieses Beispiel ein.

curl --fail --silent --show-error \
  -H "Authorization: Bearer $CALLMETRA_API_KEY" \
  "$CALLMETRA_ORIGIN/api/v1/calls?page=1&pageSize=20"

Ereignisse empfangen und senden

Eigene eingehende Anruf-Webhooks konfigurierst du unter Integrationen. Der generierte Bearer-Token ist kein lesender API-Schlüssel. Nutze schemaVersion 1, eine eindeutige Ereignis-ID, Anruf-ID, occurredAt mit explizitem Zeitzonenversatz, Richtung und Mitarbeiter-Nebenstelle. HTTP 202 bestätigt dauerhafte Annahme, nicht abgeschlossene Verarbeitung. Halte Eingangs-URLs und Tokens geheim.

Ausgehende Webhooks senden gewählte Lebenszyklus-Ereignisse an deine öffentliche HTTPS-URL. Private/lokale Ziele und Weiterleitungen sind gesperrt. Prüfe Callmetra-Timestamp und Callmetra-Signature gegen den unveränderten Request-Body. Die Signatur ist HMAC-SHA256 aus Unix-Zeitstempel, Punkt und Body; der Wert trägt das Präfix v1=. Lehne Zeitstempel außerhalb von fünf Minuten ab, vergleiche in konstanter Zeit und dedupliziere die Ereignis-ID. Die Zustellung erfolgt mindestens einmal mit bis zu acht Versuchen. Halte das Signiergeheimnis privat und prüfe keinen neu serialisierten JSON-Body.

Bei Einrichtungs- und Zustellfehlern hilft die Fehlerdiagnose.

Seitennavigation und Fehler

Listen verwenden Seitennummern ab 1 und pageSize zwischen 1 und 100. Antworten enthalten data und pagination mit page, pageSize, total und totalPages. Anruf-Filter für Zeitraum, Team, Mitarbeiter, Richtung, Status und Suche stehen in OpenAPI. Pro Schlüssel sind 120 autorisierte Anfragen pro Minute erlaubt. Beachte Retry-After bei HTTP 429. HTTP 401 bedeutet fehlende oder widerrufene Anmeldung; 403 steht für unzureichende Scopes, Rollen oder Tarifrechte. Das Fehlerobjekt enthält status, code, message und requestId. Notiere die Anfrage-ID für Support, ohne den Schlüssel weiterzugeben.

Beispiel für eigene Eingangsereignisse

Dieses fiktive Beispiel beginnt einen eingehenden Anruf. Sende call.answered und call.ended anschließend mit derselben callId und jeweils neuer Ereignis-ID. Nutze tatsächliche Ereigniszeiten mit explizitem Versatz. Spiele dieses Beispiel nicht in eine produktive Verbindung ein.

{
  "schemaVersion": 1,
  "id": "example-start-1",
  "event": "call.started",
  "callId": "example-call-1",
  "occurredAt": "2026-11-21T10:00:00+01:00",
  "direction": "inbound",
  "employeeExtension": "101",
  "number": "+12025550101"
}

Ausgehende Signatur prüfen

Diese Empfangsfunktion prüft den rohen UTF-8-Body vor dem Parsen. Übergib das Signiergeheimnis aus sicherer Server-Konfiguration. Dedupliziere nach der Prüfung Callmetra-Event-Id dauerhaft, bevor du Folgeaktionen ausführst.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp || '') ||
      Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody).digest('hex');
  const left = Buffer.from(expected);
  const right = Buffer.from(signature || '');
  return left.length === right.length && timingSafeEqual(left, right);
}
callmetra. · Every call. Measurable insights.Kontakt ↗