API-Referenz v1

Der schnellste Weg, ein CRM mit Heilo zu verbinden. Die vollständige API-Referenz finden Sie weiter unten.

1. Stellen Sie einen Webhook-Endpunkt in Ihrem CRM oder Ihrer Middleware bereit (ohne Code: verwenden Sie Zapier/Make — siehe die Anleitung unten).
2. Fügen Sie in Heilo (Einstellungen → Integrationen) ein Abonnement für call.completed hinzu (optional auch call.outbound.attempted).
3. Empfangen Sie call.completed und verifizieren Sie die Signatur (Heilo-Signature-Header, HMAC — siehe unten).
4. Deduplizieren Sie nach event_id (heilo-event-id-Header); data.call_id gruppiert Ereignisse desselben Anrufs.
5. Ordnen Sie die Felder Ihrem CRM zu: einen Kontakt anhand der Telefonnummer finden/erstellen, einen Lead/Deal erstellen und eine Aktivität/Notiz anhängen (Zusammenfassung + Aufzeichnungslink).

Kein Code? Die No-Code-Verbindungsanleitung (Zapier/Make) führt Sie Schritt für Schritt durch.

Die öffentliche API verwendet Bearer-Token. Generieren Sie einen API-Schlüssel über die Karte „API-Schlüssel“ auf der Integrationsseite und senden Sie ihn im Header:

Authorization: Bearer hk_live_AbC1MnPq...

Heilo hat drei Authentifizierungsmodi:

• Bearer (API-Schlüssel hk_live_…) — für die öffentliche API. Kein CSRF, keine Cookies.
• Session-Cookies — für die Web-App (heilo.io). NICHT für die öffentliche API verwenden.
• HMAC-SHA256 — für Webhooks, die Heilo an IHREN Endpunkt sendet (Sie verifizieren den Signatur-Header).

Das Feld environment in der /me-Antwort hat heute immer den Wert live. Test-Schlüssel sind geplant.

Alle öffentlichen Endpunkte liegen unter /api/v1/. Produktion:

https://www.heilo.io/api/v1

Jeder /api/v1-Endpunkt erfordert Bearer. /me unten dient zur Schlüssel-Introspektion; das Lesen von Anrufen finden Sie im Abschnitt „Anrufe“. Behandeln Sie bei der Integration eines CRM Webhooks als primäre Datenquelle — REST dient zur Introspektion und zum Lesen ausgewählter Metadaten.

curl https://www.heilo.io/api/v1/me \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."

{
  "success": true,
  "data": {
    "api_key_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
    "user_id": "5f4e3d2c-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "organization_id": "7a8b9c0d-1e2f-4a3b-9c8d-7e6f5a4b3c2d",
    "scopes": ["read.calls", "manage.webhooks"],
    "rate_limit_per_hour": 1000,
    "environment": "live"
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

Lese-Endpunkte für Anrufe. Erfordern den Scope read.calls.

curl "https://www.heilo.io/api/v1/calls?limit=20&direction=inbound" \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."

{
  "success": true,
  "data": {
    "items": [
      {
        "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "direction": "inbound",
        "caller_phone": "+48600100200",
        "customer_phone_e164": "+48600100200",
        "caller_name": "Jan Kowalski",
        "duration": 87,
        "crm_status": "new",
        "review_status": null,
        "outbound_lifecycle": null,
        "transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "..." },
        "created_at": "2026-06-03T12:34:56Z"
      }
    ],
    "has_more": false,
    "page": 1,
    "limit": 20
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

curl https://www.heilo.io/api/v1/calls/<id> \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."

Aufzeichnungsdateien werden NICHT über die API bereitgestellt — sie werden gemäß der gesetzlichen Aufbewahrung (DSGVO) gelöscht. Die API gibt Anruf-Metadaten und Transkripttext zurück.

Stündliche Limits pro Schlüssel und pro Benutzer (Summe aller Schlüssel). Zurücksetzung zur vollen UTC-Stunde. Jede Anfrage zählt, unabhängig vom Antwortstatus.

Bei Überschreitung geben wir 429 mit dem Retry-After-Header zurück (Sekunden bis zum Zurücksetzen):

HTTP/1.1 429 Too Many Requests
Retry-After: 1842
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-03T13:00:00Z

Alle Fehler geben eine einheitliche JSON-Struktur mit error.code (stabil) und error.message (menschenlesbar, kann sich ändern) zurück. Protokollieren Sie den Code, nicht die Nachricht.

{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "Per-key rate limit 1000/h exceeded" },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

Der Code SUBSCRIPTION_INACTIVE tritt in zwei Situationen auf: HTTP 402 — das Heilo-Abonnement ist abgelaufen (Zahlung), und HTTP 409 — das Webhook-Abonnement ist pausiert (z. B. bei der Test-Aktion); klicken Sie dann zuerst auf „Erneut verifizieren“.

Heilo sendet nach jedem Ereignis ein POST mit JSON an Ihren Endpunkt. Abonnements werden über die Karte „Webhook-Abonnements“ erstellt — bei der Aktivierung ist ein Handshake erforderlich. Jede Anfrage enthält eine HMAC-Signatur, die Sie verifizieren müssen:

POST <your URL>
content-type: application/json
heilo-signature: t=1717423396,v1=4f3a...
heilo-event-id: 1bf3a5e2-...
heilo-event-type: call.completed

{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-...",
  "event_type": "call.completed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-06-03T12:34:56Z",
  "data": { /* see the setup guide for the full schema */ }
}

Wiederholungs- und Pausierungsrichtlinie:

• Vorübergehende Fehler (HTTP 408/429/5xx, Netzwerk) werden mit exponentiellem Backoff wiederholt (2 Min, 5 Min, 30 Min, 2 Std) — danach Dead-Letter nach 5 Versuchen.
• Permanente Fehler (HTTP 401/403/422) pausieren das Abonnement sofort — keine Wiederholungen.
• 50 aufeinanderfolgende vorübergehende Fehler oder 2 aufeinanderfolgende HTTP 410 Gone (z. B. gelöschtes Make-Szenario) pausieren das Abonnement ebenfalls.
• Setzen Sie ein pausiertes Abonnement mit „Erneut verifizieren“ fort — ein neuer Handshake reaktiviert die Warteschlange.

Wird ein Abonnement automatisch pausiert, senden wir eine E-Mail an die Adresse des Kontoinhabers. Ereignisse aus der Dead-Letter-Warteschlange können Sie mit der Schaltfläche „Erneut senden“ im Zustellungsprotokoll erneut senden — nachdem das Abonnement erneut verifiziert wurde.

Heilo unterstützt zwei Aktivierungsmodelle für Webhook-Abonnements. Der Standard (permissiv) passt zu Zapier / Make / typischen CRM-Endpunkten. Strikt entspricht dem Modell der Slack Events API — nützlich für eigene Server, die die Challenge synchron zurückgeben können.

{"challenge":"<echo of the challenge field from Heilo's POST>"}

Sie wählen den Modus beim Erstellen des Abonnements (verification_mode in POST /api/v1/webhook-subscriptions, Standard permissiv). Eine Änderung des Modus nach der Erstellung erfordert Löschen + Neuerstellen — beabsichtigt, da sich dadurch die Vertragssemantik ändert.

Limits: max. 20 aktive Abonnements pro Konto (per Umgebungsvariable überschreibbar). Ein Abonnement wird nach 50 aufeinanderfolgenden vorübergehenden Fehlern oder 2 aufeinanderfolgenden HTTP 410 automatisch pausiert und sofort bei HTTP 401/403/422.

Stripe-kompatibles Format. signed_string = "<unix_ts>.<raw_body>" (durch Punkt getrennt). Verifizieren Sie immer den ROHEN Anfragetext (vor dem JSON-Parsing) — jede Normalisierung verändert die Signatur.

signed_string = "<unix_timestamp>.<raw_request_body>"
signature     = HMAC-SHA256(signing_secret, signed_string).hex()
header        = "t=<unix_timestamp>,v1=<signature>"

import { createHmac, timingSafeEqual } from 'crypto';

// rawBody MUST be the exact received bytes — do NOT re-serialize the JSON.
function verifyHeiloSignature(rawBody, header, signingSecret, toleranceSec = 300) {
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=').map((s) => s.trim()))
  );
  const t = Number(parts.t);
  const sig = parts.v1;
  if (!Number.isFinite(t) || !sig) return false;

  // Asymmetric tolerance: reject old replays; allow only small clock skew ahead.
  const now = Math.floor(Date.now() / 1000);
  if (now - t > toleranceSec || t - now > 60) return false;

  const expected = createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(sig, 'utf8');
  // timingSafeEqual THROWS on length mismatch — length-check first.
  return a.length === b.length && timingSafeEqual(a, b);
}

Eine Standardtoleranz von 300 s (5 Min) verhindert Replay-Angriffe. Server-Uhren müssen NTP-synchronisiert sein.

Das Signatur-Secret zeigen wir nur einmal an — beim Erstellen des Abonnements. Wenn Sie es verlieren oder ein Leck vermuten: Löschen Sie das Abonnement und erstellen Sie es mit derselben URL neu (die Adresse in Zapier/Make ändert sich nicht). Eine Rotation des Secrets ohne Löschen ist geplant.

Wählen Sie event_types beim Erstellen eines Abonnements. Jedes Ereignis hat eine eindeutige event_id (UUID v5) und wird pro Abonnement dedupliziert.

Das erste Ereignis, das Sie erhalten, ist webhook.test — eine Testnachricht mit data._test = true. Nutzen Sie sie zum Zuordnen der Felder oder filtern Sie sie heraus.

Unten das data-Objekt jedes Ereignisses. Feldnamen, Typen und Aufzählungswerte sind Teil des API-Vertrags und ändern ihre Bedeutung innerhalb von v1 nicht; mit der Zeit können neue, optionale Felder hinzukommen.

{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-...",        // same value as heilo-event-id header
  "event_type": "call.completed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-06-03T12:34:56Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "caller_phone": "+48600100200",
    "customer_phone_e164": "+48600100200",
    "duration": 87,
    "recording_url": "https://www.heilo.io/api/v1/calls/.../recording.mp3?token=...&exp=...",
    "transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "..." },
    "transcript_original": "..."
  }
}