Zum Inhalt springen

API-Referenz v1

REST- + Webhooks-Integrationsreferenz (Version 2026-06-15)

v1 · 2026-06-15Beta

Schnellstart für die CRM-Integration

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

Integrieren Sie webhook-first: Das Ereignis call.completed ist die primäre Datenquelle (es enthält den Aufzeichnungslink und das verarbeitete Transkript). REST /calls ist eine Ergänzung — Introspektion und Lesen ausgewählter Metadaten.

  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.

Authentifizierung

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).
Berechtigung (Scope)Bedeutung
read.callsAnrufe lesen: GET /api/v1/calls, GET /api/v1/calls/:id
read.recordingsErzeugt über `GET /calls/:id/recording-url` einen Link zum Audio eines Anrufs. Getrennt von `read.calls`, weil Audio eine andere Einwilligung ist als Metadaten — ein bestehender Schlüssel erhält ihn nicht, du legst einen neuen mit ausdrücklichem Aufnahmezugriff an.
read.transcriptsFügt `GET /calls/:id` den Transkripttext hinzu: `transcript_original`, `transcript_edited` und `transcript_edited_at`. Getrennt von `read.calls`, weil der Wortlaut eines Gesprächs eine andere Einwilligung ist als Metadaten — ein bestehender Schlüssel erhält ihn nicht, man erstellt einen neuen Schlüssel mit ausdrücklichem Transkriptzugriff. Ohne ihn fehlen diese Felder, und der Aufruf antwortet weiterhin mit 200. Erfordert zusätzlich `read.calls`: ein Schlüssel nur mit `read.transcripts` erhält 403, und das Erstellen wird mit 400 abgelehnt.
write.calls, read.contacts, write.contacts, manage.webhooks, manage.api_keysReserviert für geplante API-Endpunkte. Ein neuer Schlüssel kann damit nicht erstellt werden (400 BAD_REQUEST). Ein älterer Schlüssel kann noch einen davon tragen, er gewährt nichts.

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

Basis-URL und Version

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

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

Aktuelle Version

v1 · 2026-06-15

Das Datum ist die API-Versionskennung (datumsbasiert), nicht das heutige Datum.

Status

Beta

Die Heilo-API verwendet eine datumsbasierte Version. Nur Breaking Changes erhöhen die Hauptversion (v1 → v2). Das Hinzufügen von Feldern oder Endpunkten ist nicht breaking, ebenso neue Felder in Webhook-Payloads.

Abwärtskompatibel: neue Antwortfelder, neue Felder in Webhook-Payloads, neue event_types, neue Endpunkte. Breaking Change = neue Hauptversion (v2). Die alte Version wird mind. 12 Monate nach Ankündigung von v2 unterstützt.

Rate Limits

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.

Pro Schlüssel

1000 req/h

Pro Konto (Summe der Schlüssel)

5000 req/h

Jede erfolgreiche Antwort enthält X-RateLimit-Limit (das Stundenlimit des Schlüssels), X-RateLimit-Remaining (verbleibende Anfragen des Schlüssels in dieser Stunde) und X-RateLimit-Reset (Zeitpunkt des Zurücksetzens, ISO 8601). Bei Überschreitung antworten wir mit 429 und dem Header Retry-After (Sekunden bis zum Reset):

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

Fehler

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" }
}
{
  "success": false,
  "error": { "code": "BAD_REQUEST", "message": "Validation failed", "details": { "errors": [{ "path": "scopes", "message": "Required" }] } },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}
HTTPcodeBedeutung
400BAD_REQUESTFehlerhafte Query- oder Body-Parameter (generische Validierung)
401UNAUTHORIZEDFehlender / ungültiger Bearer-Token
402SUBSCRIPTION_INACTIVEAbonnement inaktiv — erneuern Sie die Abrechnung, um den Schlüssel wieder zu aktivieren
403FORBIDDENDer Schlüssel verfügt nicht über den erforderlichen Scope
404NOT_FOUNDDie Ressource existiert nicht oder liegt außerhalb der Organisation des API-Schlüssels.
400VALIDATION_ERROREin Parameter hat eine Prüfung nicht bestanden (z. B. phone ist keine Telefonnummer)
429RATE_LIMITEDStundenlimit überschritten (siehe Retry-After)
500DATABASE_ERRORServer-/Datenbankfehler — kann mit Backoff gefahrlos wiederholt werden
503MAINTENANCEÖffentliche API vorübergehend deaktiviert (Kill-Switch)
503SERVICE_UNAVAILABLEEin für den Aufruf nötiger Teil des Dienstes ist nicht verfügbar (zum Beispiel können gerade keine Aufnahme-Links erzeugt werden) — mit Backoff wiederholen
503WEBHOOK_ACTIVATION_LOCKEDDas Einschalten von Webhook-Abonnements ist für eine Migration angehalten; bestehende Abonnements laufen weiter — später erneut versuchen
422SUBSCRIPTION_LIMITDie Organisation hat ihr Limit an Webhook-Abonnements erreicht (HTTP 422) — zuerst ein ungenutztes löschen

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“.

Ein Fehler kann zusätzlich error.details mit Einzelheiten enthalten, zum Beispiel die fehlgeschlagenen Felder einer Validierung; das Feld kann fehlen. Stabil ist der Code.

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.

API-Schlüssel-Introspektion — gibt die Key-ID, user_id, scopes und das Rate Limit zurück. Nützlich für den „Verbindungstest“ von Zapier/Make.

Anwendungsfall: Zapier-Verbindungstest während der Einrichtung einer benutzerdefinierten Integration. Eine 200-Antwort beweist, dass Schlüssel + Netzwerk funktionieren.

Anfrage
curl https://www.heilo.io/api/v1/me \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Antwort
{
  "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", "read.recordings"],
    "rate_limit_per_hour": 1000,
    "environment": "live"
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

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

Listet die Anrufe der Organisation auf. Paginierung (page/limit≤100), Filter: direction, status, Datumsbereich (dateFrom/dateTo). Gibt has_more zurück.

Die Liste beginnt mit dem neuesten Gespräch (created_at absteigend) und wird seitenweise geliefert; ein Gespräch, das während des Blätterns eintrifft, verschiebt die Zeilen. Entdoppeln Sie nach call_id und lesen Sie die erste Seite erneut, um aufzuholen. Das ist kein Export der gesamten Historie.

Abfrageparameter

ParameterTypWerte
pageintab 1 (Standard 1)
limitint1–100 (Standard 20)
directionenuminbound | outbound
statusenumnew | to_call | contacted | qualified
dateFrom / dateTostringDatum YYYY-MM-DD oder Datum mit Uhrzeit in UTC, z. B. 2026-06-03T12:34:56Z (ein Offset wie +02:00 ergibt 400). Ein Datum allein in dateTo umfasst den ganzen UTC-Tag, daher liefert dateTo=2026-06-03 auch die Gespräche vom 3. Juni; ein Datum mit Uhrzeit ist ein genauer Zeitpunkt, inklusive
phonestringdie Kundennummer des Gesprächs, mit Ländervorwahl; Leerzeichen, Bindestriche und das führende + sind optional, z. B. +48 600 100 200
Anfrage
curl "https://www.heilo.io/api/v1/calls?limit=20&direction=inbound" \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Antwort
{
  "success": true,
  "data": {
    "items": [
      {
        "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "direction": "inbound",
        "caller_phone": "+48600100200",
        "customer_phone_e164": "+48600100200",
        "customer_phone_national": "600 100 200",
        "company_phone_e164": "+48222630000",
        "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "caller_name": "Jan Kowalski",
        "duration": 87,
        "crm_status": "new",
        "review_status": null,
        "outcome": "quote_to_send",
        "outcome_source": "ai",
        "outbound_lifecycle": null,
        "transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "...", "followup_email": null },
        "created_at": "2026-06-03T12:34:56Z"
      }
    ],
    "has_more": false,
    "page": 1,
    "limit": 20
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

Ruft einen einzelnen Anruf anhand der id ab. 404, wenn er nicht zur Organisation des Schlüssels gehört oder gelöscht wurde.

An diesem Endpunkt enthält das Analyseobjekt transcript_processed summary, service_needed, caller_name und followup_email sowie subject, lead_score (1–10, Schätzung des Modells), detected_language und client_city: dieselben Werte, die der Webhook call.completed sendet. Ein Feld, das die Analyse nicht erzeugt hat, ist null. has_recording zeigt, ob Audio gespeichert ist; das Audio selbst kommt von GET /calls/:id/recording-url mit dem Scope read.recordings.

Mit dem Scope read.transcripts enthält die Antwort zusätzlich transcript_original (null, wenn das Gespräch kein brauchbares Transkript hat: noch in Verarbeitung, fehlgeschlagen oder keine Sprache), transcript_edited und transcript_edited_at (null, wenn niemand es bearbeitet hat). Ohne den Scope fehlen diese drei Felder (nicht null), und die Antwort ist weiterhin 200.

Die Antwort enthält außerdem user_notes: die Einträge, die Personen in Heilo zum Gespräch geschrieben haben („Gesprächsnotizen“), älteste zuerst, höchstens 200, ein leeres Array, wenn es keine gibt. Der Listen-Endpunkt GET /calls liefert sie nicht. Das Beispiel ist gekürzt; die übrigen Felder entsprechen denen der Liste. Um über Änderungen der Einträge informiert zu werden, abonnieren Sie call.user_notes.changed.

Anfrage
curl https://www.heilo.io/api/v1/calls/<id> \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Antwort
{
  "success": true,
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "duration": 87,
    "outcome": "quote_to_send",
    "outcome_source": "ai",
    "created_at": "2026-06-03T12:34:56Z",
    "transcript_processed": {
      "caller_name": "Anna Nowak",
      "summary": "Asks for a quote for a bathroom renovation.",
      "service_needed": "bathroom renovation",
      "followup_email": null,
      "subject": "Bathroom renovation quote",
      "lead_score": 7,
      "detected_language": "en",
      "client_city": "Gdańsk"
    },
    "has_recording": true,
    "user_notes": [
      {
        "id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "body": "Klient prosi o telefon po 10:00.",
        "source": "live",
        "author": {
          "id": "2ce127a0-c621-483d-b576-e68f69d95e84",
          "name": "Anna Nowak"
        },
        "noted_at": "2026-09-08T10:01:12Z",
        "recording_offset_seconds": 72,
        "created_at": "2026-09-08T10:01:12Z",
        "updated_at": "2026-09-08T10:01:12Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-06-03T12:34:56Z"
  }
}

Ein frisch signierter Link zur Audiodatei des Anrufs, 15 Minuten gültig. Es ist eine Download-Berechtigung mit Ablaufdatum, keine dauerhafte Referenz: speichere die `call_id` und frage erneut, denn ein in einem CRM-Feld abgelegter Link ist binnen einer Stunde tot. Der Link im Webhook `call.recording.ready` ist sieben Tage signiert — über diesen Endpunkt erreichst du das Audio danach.

  • 200 — der Link und der Zeitpunkt, an dem er aufhört zu funktionieren.
  • 409 `RECORDING_NOT_READY` — der Anruf gehört dir, das Audio ist noch nicht eingetroffen. Frage gleich noch einmal.
  • 409 `RECORDING_WITHHELD` — der Anruf liegt im Papierkorb oder ist zur Löschung vorgemerkt. Einen Anruf im Papierkorb kann der Kunde 30 Tage lang wiederherstellen, frage also weiter, statt die Aufnahme bei dir abzuschreiben; ein Anruf mit Aufnahme wird 30 Tage nach dem Verschieben in den Papierkorb gelöscht. Eine vorgemerkte Löschung lässt sich nicht rückgängig machen: verwende die Aufnahme nicht mehr. In beiden Fällen bekommst du nach dem Löschen 410.
  • 410 `RECORDING_DELETED` — die Aufnahme wurde gelöscht (Aufbewahrungsfrist, Papierkorb nach 30 Tagen oder Löschanfrage), sie ist nicht wiederherstellbar. Hör auf zu fragen und zu queuen.
  • 410 `RECORDING_NOT_CAPTURED` — dieser ausgehende Anruf wurde nie aufgezeichnet und es wird nie eine Aufzeichnung dafür geben: Das Capture-Gate hat ihn beim Start abgelehnt, er lief im Modus no_recording oder endete ohne Gespräch. Hör auf zu fragen — es gibt keinen Grund für einen erneuten Versuch. Ein eingehender Anruf, dessen Aufzeichnung abgelehnt wurde, antwortet weiter mit 409, weil noch eine Aufzeichnung folgen kann.

Die Antwort wird mit `Cache-Control: no-store` ausgeliefert, weil der Body eine Berechtigung enthält. Die Berechtigung wird beim Abruf der Datei erneut geprüft, nicht nur beim Erzeugen des Links — ein zwischenzeitlich gelöschter Anruf ist sofort nicht mehr lesbar.

Anfrage
curl https://www.heilo.io/api/v1/calls/<id>/recording-url \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Antwort
{
  "success": true,
  "data": {
    "url": "https://www.heilo.io/api/v1/calls/<id>/recording.mp3?token=...&exp=...",
    "expires_at": "2026-09-15T12:15:00.000Z"
  }
}

Weder die Gesprächsliste noch die Details liefern eine Aufnahmedatei oder einen Link; die Details sagen nur, ob eine Aufnahme existiert (has_recording). Den Aufnahme-Link erhalten Sie im Webhook, nach seinem Ablauf über `GET /calls/:id/recording-url`. Aufnahmen können nach den Regeln zu Aufbewahrung und DSGVO gelöscht werden.

Was REST liefert und was nur ein Webhook liefert

Die beiden Kanäle tragen nicht dasselbe, und der Unterschied entscheidet die Wahl. REST ist dauerhaft: Ein Gespräch lesen Sie daraus jederzeit. Ein Webhook ist reichhaltiger, kommt aber einmal, und ein Teil seines Inhalts verfällt.

DatenRESTWebhook
Gesprächsmetadaten: Richtung, Nummern, Dauer, Datumjaja
CRM-Status und Prüfstatusjanein
Anrufergebnis und wer es gesetzt hatjaja
Gesprächsnotizen (REST: nur in GET /calls/:id)jaja
Zusammenfassung, Anrufername, Kundenbedarfjaja
Der Rest der Analyse: Stadt, Adresse, Lead-Score, Wunschtermin, Spracheteilweise: GET /calls/:id liefert Stadt, Lead-Score und Sprache; Adresse und Wunschtermin kommen nur aus dem Webhookja
Das wortwörtliche Transkriptja, GET /calls/:id mit read.transcriptsja
Aufnahme-Linkja, über /calls/:id/recording-urlja, 7 Tage gültig

Daraus folgt die praktische Regel: Der Webhook liefert alles im Moment der Verarbeitung, REST liefert danach die Details eines einzelnen Gesprächs, mit der erweiterten Analyse und, mit read.transcripts, dem Transkript. Die Aufnahme holen Sie getrennt — fragen Sie /calls/:id/recording-url nach einem frischen 15-Minuten-Link, statt den siebentägigen aus dem Payload zu speichern.

Spezifikation und eine echte Anfrage

Dieselben vier Operationen, für Maschinen geschrieben: OpenAPI 3.1. In Postman oder Insomnia importieren oder einen Client in Ihrer Sprache generieren.

OpenAPI 3.1 herunterladen

Spezifikation und eine echte Anfrage

Senden Sie hier eine Anfrage und prüfen Sie Ihren Schlüssel, bevor Sie Code schreiben.

Dies ruft die echte API mit Ihrem echten Schlüssel auf und liefert Ihre eigenen Daten. Der Schlüssel bleibt in diesem Browser-Tab — wir speichern ihn nie.

Ausgehende Webhooks

Heilo sendet signierte JSON-Ereignisse an Ihren Endpunkt. Erstellen Sie Abonnements in der Karte Webhook-Abonnements. Die Aktivierung verwendet einen separaten, unsignierten Handshake webhook.subscription.verify, der keine Geschäftsdaten anlegen darf.

Die Endpunktadresse muss https sein, öffentlich erreichbar und darf nicht auf eine private oder interne Adresse zeigen (localhost, 10.x, 192.168.x und ähnliche). Zum Testen vom eigenen Rechner machen Sie ihn über einen öffentlichen Tunnel erreichbar. Endpunkte werden nur unter Einstellungen → Integrationen angelegt; kein API-Aufruf legt einen an.

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:

  • Bei vorübergehenden Fehlern gibt es insgesamt höchstens 5 Versuche: nach 2 Min., 5 Min., 30 Min. und 2 Std., mit zufälliger Zeitverschiebung (Jitter) bei späteren Versuchen. Nach dem fünften Fehler endet die Zustellung als Dead Letter.
  • 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 schaltet den Versand wieder ein. Ereignisse, die beim Pausieren bereits in der Warteschlange warteten, sendet er nicht: Sie landen in der Dead-Letter-Warteschlange und müssen mit „Erneut senden“ im Zustellungsprotokoll erneut gesendet werden.

Pausiert Heilo ein Abonnement automatisch, weil Ihre Adresse wiederholt Fehler liefert, senden wir eine E-Mail an die Person, die es betreut — meist die Person, die es angelegt hat. Gibt es dieses Konto nicht mehr, erhalten die Inhaber der Organisation die E-Mail. 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.

2xx bestätigt den HTTP-Empfang, nicht den Abschluss einer Automatisierung oder das Speichern im CRM. Zustellungen können sich wiederholen oder in anderer Reihenfolge eintreffen. Heilo gleicht aktuelle Lücken in einem begrenzten Zeitfenster aus, nicht die gesamte Historie. Prüfen Sie Zustellprotokoll und CRM getrennt.

Verifizierungsmodi

Der unsignierte Handshake enthält nur event_type = webhook.subscription.verify und challenge. Bestätigen Sie nur den Endpunkt; starten Sie keine Geschäftsverarbeitung. Beide Modi verwenden dieselbe Anfrage:

{
  "event_type": "webhook.subscription.verify",
  "challenge": "example-verification-token"
}

Modus permissive (Standard)

Jede 2xx-Antwort aktiviert das Abonnement; der Antwortinhalt wird ignoriert. Dies ist der Standardmodus für No-Code-Empfänger.

Modus strict (Opt-in)

Antworten Sie mit 2xx und JSON mit exakt dem von Heilo empfangenen challenge-Wert:

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

Wählen Sie den Modus beim Erstellen. Eine Änderung erfordert Löschen und Neuerstellen des Abonnements. Verwaltungsrouten erfordern eine angemeldete Sitzung und CSRF-Schutz; sie sind nicht mit einem API-Schlüssel zugänglich.

Limits: max. 20 aktive Abonnements pro Organisation (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.

HMAC-Verifizierung (signing_secret)

Signierte Ereignisse einschließlich des manuellen webhook.test verwenden Heilo-Signature mit HMAC-SHA256 über Zeitstempel + Punkt + ursprüngliche Anfragebytes. Prüfen Sie die Signatur vor dem Parsen der Geschäftsdaten. Nur der Handshake zur Endpunktbestätigung ist unsigniert.

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 'node:crypto';

// Pass the exact received Buffer (e.g. Express raw parser), never JSON.stringify(req.body).
// signingSecrets: every secret you currently trust, tried in constant time each.
// During a secret rotation pass [newSecret, oldSecret]; remove the old one once
// Heilo's grace window ends. Heilo itself always sends exactly ONE v1 signature —
// this list is what lets your receiver accept it under either secret while both
// are live, never a second signature to parse.
function verifyHeiloSignature(rawBody, header, signingSecrets) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!match) return false;
  const timestamp = Number(match[1]);
  const now = Math.floor(Date.now() / 1000);
  // Receiver policy: at most 10 minutes old or 5 minutes ahead (clock skew).
  if (!Number.isSafeInteger(timestamp) || now - timestamp > 600 || timestamp - now > 300) return false;
  // One string is accepted too. Empty entries are dropped: an HMAC key of ''
  // is valid, so a blanked env var (OLD_SECRET=) would let anyone sign events.
  const secrets = [].concat(signingSecrets).filter((s) => typeof s === 'string' && s.length > 0);
  if (secrets.length === 0) return false;
  const actual = Buffer.from(match[2], 'hex');
  return secrets.some((signingSecret) => {
    const expected = createHmac('sha256', signingSecret)
      .update(match[1] + '.')
      .update(rawBody)
      .digest();
    return actual.length === expected.length && timingSafeEqual(actual, expected);
  });
}

function receiveHeiloWebhook(rawBody, signatureHeader, signingSecrets) {
  if (!signatureHeader) {
    // The ONLY unsigned exception confirms the endpoint; never enqueue it for CRM writes.
    const probe = JSON.parse(rawBody.toString('utf8'));
    if (probe && typeof probe === 'object' && !Array.isArray(probe)
      && Object.keys(probe).length === 2
      && probe.event_type === 'webhook.subscription.verify'
      && typeof probe.challenge === 'string') {
      return { kind: 'verification', response: { challenge: probe.challenge } };
    }
    throw new Error('Missing Heilo-Signature');
  }
  if (!verifyHeiloSignature(rawBody, signatureHeader, signingSecrets)) throw new Error('Invalid Heilo-Signature');
  return { kind: 'event', event: JSON.parse(rawBody.toString('utf8')) };
}

// HTTP adapter: limit body size; map verification to 200 JSON response.
// Signature errors -> 401 (pauses delivery; fix the secret, then Reverify). JSON errors -> 400.
// For kind=event: validate the envelope and chosen event_type, ignore webhook.test
// in business flows, then durably deduplicate/enqueue by event_id BEFORE returning 2xx.
// Enqueue failure: return 503. An HTTP acknowledgement is not proof of a CRM write.

Die Beispiele akzeptieren Signaturen bis zu 600 Sekunden (10 Minuten) alt und 300 Sekunden (5 Minuten) in der Zukunft, entsprechend dem bestehenden Heilo-Prüfer. Synchronisieren Sie Serveruhren. Zeitprüfungen begrenzen das Replay-Fenster; Deduplizierung nach event_id bleibt erforderlich.

Das Signatur-Secret zeigen wir nur einmal an — beim Erstellen des Abonnements. Haben Sie es verloren oder vermuten Sie ein Leck? Öffnen Sie das Abonnement unter Einstellungen → Integrationen → Webhooks und rotieren Sie es dort — siehe „Rotation des Secrets“ unten. Das Abonnement muss dafür nicht gelöscht und neu erstellt werden.

Rotation des Secrets

Heilo sendet immer genau eine v1-Signatur, nie zwei gleichzeitig. Die Rotation funktioniert über die Installationsreihenfolge, nicht dadurch, dass Ihr Empfänger mehrere Signaturen parsen lernt.

  1. Bereiten Sie ein neues Secret in den Abonnement-Einstellungen vor. Es wird einmal angezeigt und wartet bis zu 24 Stunden auf die Aktivierung.
  2. Installieren Sie das neue Secret NEBEN dem aktuellen — Ihr Empfänger muss eine Signatur akzeptieren, die mit einem von beiden erstellt wurde.
  3. Senden Sie optional einen mit dem neuen Secret signierten Test. Er trägt den Header Heilo-Secret-Rotation-Id und einen gewöhnlichen webhook.test-Body; eine 2xx-Antwort beweist nicht, dass Ihr Empfänger die Signatur geprüft hat — bestätigen Sie das in Ihrem eigenen Log.
  4. Aktivieren Sie die Rotation.
  5. Behalten Sie das alte Secret noch 1 Stunde nach der Aktivierung bei, dann entfernen Sie es.

Heilo ändert nichts an Ihrem Empfänger. In diesem Zeitfenster muss Ihr Empfänger eine Signatur akzeptieren, die mit einem der beiden Secrets erstellt wurde.

Notfall: das Secret ist durchgesickert

Eine Notfall-Rotation pausiert den Versand sofort. Installieren Sie NUR das neue Secret — behandeln Sie das alte als kompromittiert — und aktivieren Sie dann; es gibt keine Karenzzeit. Setzen Sie den Versand danach mit „Erneut verifizieren“ fort. Bereits in der Warteschlange stehende Zustellungen werden beim Pausieren übersprungen; senden Sie sie aus dem Zustellprotokoll erneut.

Secret verloren, aber kein Leck? Eine normale Rotation funktioniert trotzdem — das Abonnement muss nicht gelöscht werden.

Ereignistypen

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

webhook.test wird von der manuellen Aktion Test gesendet und hat data._test = true. Es läuft durch dieselbe Zustellwarteschlange wie echte Ereignisse, kann also einen Moment nach dem Klick eintreffen, und sein Ergebnis erscheint als Status im Zustellprotokoll. Nutzen Sie es zum Zuordnen der Felder und schließen Sie es dann von der Geschäftsverarbeitung aus. Der separate Aktivierungs-Handshake ist webhook.subscription.verify.

event_typeBeschreibung
call.completedAnruf abgeschlossen, Transkript bereit
call.missedEingehender Anruf ohne Transkript beendet (verpasst, ohne Nachricht oder nicht aufgezeichnet)
call.outbound.attemptedAusgehender Anrufversuch hat einen Endzustand erreicht (verbunden oder fehlgeschlagen)
call.recording.readyAufzeichnungsdatei zum Download verfügbar
call.transcribedTranskript bereit (getrennt von call.completed)
call.failedAnruf fehlgeschlagen (besetzt/keine Antwort/Fehler)
call.outbound.lifecycle_repairedKorrektur des ausgehenden Lebenszyklus — Anrufstatus repariert
call.deletion_scheduledAnruf zur Löschung vorgemerkt (DSGVO Art. 17, Aufbewahrung)
call.recording.deletedAufzeichnung gelöscht (DSGVO)
call.followup_email.draftedE-Mail-Entwurf für Follow-up bereit
call.outcome.changedAnrufergebnis gesetzt oder geändert
call.user_notes.changedGesprächsnotizen hinzugefügt, geändert oder gelöscht
call.tracker.matchedTracker getroffen
contact.createdNeuer Kontakt erstellt
contact.updatedKontakt aktualisiert

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.

call.completed

Wird gesendet, nachdem die Aufzeichnung und das Transkript eines abgeschlossenen Anrufs verarbeitet wurden. Die primäre Datenquelle für ein CRM — vollständige Nutzdaten (einschließlich recording_url und des verarbeiteten Transkripts).

{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.completed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "caller_phone": "+447700900123",
    "customer_phone_e164": "+447700900123",
    "customer_phone_national": "07700 900123",
    "company_phone_e164": "+48222630000",
    "call_created_at": "2026-09-08T10:00:00Z",
    "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "duration": 87,
    "recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
    "transcript_processed": {
      "caller_name": "Alicja Testowa",
      "counterparty_name": null,
      "counterparty_email": null,
      "caller_location": "Warszawa, Mokotów",
      "client_address": "ul. Przykładowa 10",
      "client_city": "Warszawa",
      "client_country": "Poland",
      "service_needed": "Tynki gipsowe w mieszkaniu 65m²",
      "services_match": true,
      "preferred_date": "w przyszłym tygodniu",
      "additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
      "lead_score": 7,
      "summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
      "subject": "Wycena tynków — Warszawa, 65 m²",
      "detected_language": "pl"
    },
    "transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
    "outcome": "quote_to_send",
    "outcome_source": "ai"
  }
}
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
direction'inbound' | 'outbound'Anrufrichtung.
caller_phonestring | nullGespeicherte Anrufernummer; null, falls in call.completed nicht verfügbar.
customer_phone_e164string | nullKundennummer zum CRM-Kontaktabgleich; null, falls in call.completed nicht verfügbar.
customer_phone_nationalstring | nullDieselbe Kundennummer im nationalen Format, direkt für ein CRM-Telefonfeld; null, wenn der gespeicherte Wert keine nutzbare Nummer ist, etwa bei unterdrückter Rufnummer.
company_phone_e164string | nullDie Nummer, über die dieses Gespräch einging oder ausging. In der Regel Ihre Heilo-Nummer; bei einer Weiterleitung Ihre eigene Nummer, die das Gespräch weitergeleitet hat. Damit lassen sich Notizen zuordnen, wenn Sie mehrere Nummern nutzen; null, wenn nicht erfasst.
call_created_atstring (ISO 8601) | nullWann das Gespräch in Heilo erfasst wurde (ISO 8601). Nicht identisch mit created_at im Umschlag, das den Versandzeitpunkt angibt und bei einem reparierten Ereignis Tage später liegen kann.
app_urlstring | nullDauerhafter Link zum Gespräch in Heilo. Anders als recording_url läuft er nicht ab und kann im CRM-Datensatz bleiben. Zum Öffnen ist eine Heilo-Anmeldung nötig.
durationnumberLänge der Aufzeichnung in Sekunden.
recording_urlstring | nullLink zur Aufzeichnung, 7 Tage gültig; null, wenn die Aufzeichnung zum Verarbeitungszeitpunkt noch nicht gespeichert war. Nach Ablauf holen Sie einen frischen Link über GET /calls/:id/recording-url.
transcript_processedobjectVerarbeitete Anrufanalyse — siehe die transcript_processed-Feldübersicht in diesem Abschnitt.
transcript_originalstring | nullRohes, wörtliches Transkript; null, wenn nicht verfügbar.
outcomestring | nullErgebniscode zum Zeitpunkt, an dem das Ereignis gebaut wurde (siehe Ergebniscodes unten); null, wenn niemand eines gesetzt hat. Der Schlüssel fehlt bei einem Replay eines älteren Ereignisses oder wenn Heilo ihn nicht lesen konnte. Ein späteres call.outcome.changed hat Vorrang.
outcome_source'ai' | 'user' | nullWer das Ergebnis gesetzt hat: ai (von der Analyse gewählt), user (von einer Person gewählt oder bestätigt) oder null (niemand). Fehlt immer, wenn outcome fehlt.

Die Zustellung erfolgt mindestens einmal und ohne Reihenfolgegarantie — speichern Sie idempotent. Dedup-Schlüssel: event_id. data.call_id verknüpft Ereignisse desselben Anrufs (z. B. call.completed nach call.recording.ready).

Anrufergebnis

outcome ist einer der Codes unten oder null, wenn niemand eines gesetzt hat. outcome_source sagt, wer es gesetzt hat: ai oder user. REST liefert beide Felder bei jedem Anruf; call.completed und call.transcribed tragen sie auf oberster Ebene von data; call.outcome.changed meldet jede spätere Änderung. Es können neue Codes dazukommen, behandle einen unbekannten Wert also als zusätzliche Information, nicht als Fehler.

CodeBedeutung
bookingEine Buchung, ein Besuch oder ein Termin wurde vereinbart.
cancellation_or_rescheduleDer Anrufer hat abgesagt oder bittet um einen neuen Termin.
information_requestDer Anrufer hat nach Informationen gefragt.
quote_to_sendDer Anrufer wartet auf ein Angebot.
awaiting_customer_decisionDer Kunde überlegt noch und meldet sich.
deal_wonDer Kunde hat im Gespräch einem Kauf oder einer Bestellung zugestimmt oder das Angebot angenommen. Starte eine „gewonnen“-Automation in deinem CRM nur bei outcome_source gleich user.
callback_scheduledEin weiterer Kontakt wurde vereinbart.
not_interestedDer Anrufer ist nicht interessiert.
spam_wrong_numberLeere Nachricht, Spam oder falsch verbunden.
new_opportunityEine neue Verkaufschance.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen
existing_deal_updateEin Update zu einem bestehenden Projekt.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen
follow_upEin Folgekontakt nach einem früheren Gespräch.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen
no_answerNiemand hat abgenommen.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen
voicemailDer Anrufer hat eine Sprachnachricht hinterlassen.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen
supportEine Support-Anfrage.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen
complaintEine Reklamation.veraltet: wird nicht mehr angeboten, kann bei älteren Anrufen noch vorkommen

Welcher Wert gilt

Ein call.outcome.changed-Ereignis hat Vorrang vor dem Ergebnis in call.completed und call.transcribed, in welcher Reihenfolge sie auch ankommen. Sortiere Änderungsereignisse nach data.changed_at, nie nach Ankunftszeit oder dem created_at des Umschlags. REST liefert immer den aktuellen Wert, damit holst du ein verpasstes Ereignis nach.

data.outcome ist ein Code aus der Tabelle oben. Es ist nicht dasselbe wie transcript_processed.call_outcome, ein Freitext-Satz aus der Analyse.

Zapier und Make: Der Test-Button sendet die Form von call.completed. Für ein Beispiel von call.outcome.changed wähle bei einem beliebigen Anruf in Heilo ein Ergebnis.

Gesprächsnotizen (user_notes)

user_notes ist die Liste der Einträge, die Personen in Heilo zu einem Gespräch geschrieben haben („Gesprächsnotizen“). REST liefert sie nur in GET /calls/:id; call.user_notes.changed sendet die ganze aktuelle Liste etwa fünf Minuten nach der letzten Änderung. Der Autor ist der vollständige Name aus dem Heilo-Profil, nie eine E-Mail-Adresse.

Welche Liste gilt

Jede Liste trägt eine revision, die mit jeder Änderung wächst. Ersetzen Sie Ihre Kopie nur durch eine Liste, deren revision höher ist als Ihre, und verwerfen Sie jede andere: Ein manueller erneuter Versand liefert eine ältere Liste noch einmal. REST liefert immer die aktuelle Liste, damit holen Sie ein verpasstes Ereignis nach.

source gibt an, woher ein Eintrag stammt: live (während des Gesprächs auf dem Gesprächsbildschirm getippt), after (nachträglich hinzugefügt) oder legacy (die einzelne Gesprächsnotiz von vor dem 28.10.2026). Neue Werte können hinzukommen; behandeln Sie einen unbekannten Wert als optionale Information, nicht als Fehler. recording_offset_seconds ist nur für einen live-Eintrag gesetzt, der innerhalb der Aufzeichnung getippt wurde.

Zapier und Make: Die Schaltfläche Test sendet die Form von call.completed. Für ein Beispiel von call.user_notes.changed fügen Sie in Heilo bei einem beliebigen Gespräch einen Eintrag hinzu und warten fünf Minuten.

call.missedWird in der Regel etwa zwei Stunden nach einem eingehenden Anruf gesendet, der ohne Transkript endete, und bis zu etwa 4 Std. 15 Min. später, wenn das Ende des Anrufs nicht gemeldet wurde. data.reason nennt den Grund, data.answered sagt, ob jemand abgenommen hat. Mögliche Fälle: Niemand hat abgenommen und es wurde keine Nachricht hinterlassen, der Anrufer hat vor Beginn der Aufzeichnung aufgelegt, die Aufzeichnung war für die Nummer damals ausgeschaltet, Heilo hat den Anruf absichtlich nicht aufgezeichnet, die Aufnahme war zu kurz oder es konnte kein Transkript erstellt werden. Ein angenommener Anruf ohne Transkript wird ebenfalls gesendet, mit answered gleich true; lege einen Rückruf daher nur an, wenn answered false ist. Standardmässig aus — füge call.missed zu den Ereignissen eines Endpunkts hinzu, um es zu erhalten; ein Endpunkt, der es später hinzufügt, kann auch solche Anrufe der letzten 7 Tage erhalten, prüfe daher call_created_at. Höchstens einmal pro Anruf. Die Reihenfolge ist nicht garantiert: Gibt es für dieselbe call_id ein call.completed (eine verspätete Aufnahme oder ein Anruf von über zwei Stunden), beschreibt call.completed den Anruf, egal welches zuerst ankam; abonniere beide, um solche Anrufe zu sehen. Eine Löschung in Heilo wird mit call.deletion_scheduled oder call.recording.deleted nur für einen Anruf mit Aufnahme gemeldet; ein Anruf ohne Aufnahme erhält kein Löschereignis, lösche deine Kopie bei Bedarf selbst. Anrufe, zu denen du Heilo hinzugefügt hast, sind nicht enthalten. Zapier und Make: Der Test-Button sendet die Form von call.completed; für ein call.missed-Beispiel rufe deine Heilo-Nummer an, lege auf, bevor jemand abnimmt, und warte etwa zwei Stunden.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
direction'inbound'Anrufrichtung.
customer_phone_e164string | nullKundennummer zum CRM-Kontaktabgleich; null, falls in call.completed nicht verfügbar.
customer_phone_nationalstring | nullDieselbe Kundennummer im nationalen Format, direkt für ein CRM-Telefonfeld; null, wenn der gespeicherte Wert keine nutzbare Nummer ist, etwa bei unterdrückter Rufnummer.
company_phone_e164string | nullDie Nummer, über die dieses Gespräch einging oder ausging. In der Regel Ihre Heilo-Nummer; bei einer Weiterleitung Ihre eigene Nummer, die das Gespräch weitergeleitet hat. Damit lassen sich Notizen zuordnen, wenn Sie mehrere Nummern nutzen; null, wenn nicht erfasst.
call_created_atstring (ISO 8601) | nullWann das Gespräch in Heilo erfasst wurde (ISO 8601). Nicht identisch mit created_at im Umschlag, das den Versandzeitpunkt angibt und bei einem reparierten Ereignis Tage später liegen kann.
app_urlstring | nullDauerhafter Link zum Gespräch in Heilo. Anders als recording_url läuft er nicht ab und kann im CRM-Datensatz bleiben. Zum Öffnen ist eine Heilo-Anmeldung nötig.
reason'no_recording' | 'capture_refused' | 'no_speech' | 'not_transcribed'Warum es kein Transkript gibt: no_recording — es wurde nichts aufgezeichnet (niemand hat abgenommen und keine Nachricht hinterlassen, der Anrufer hat vor Beginn der Aufzeichnung aufgelegt oder die Aufzeichnung war für diese Nummer damals ausgeschaltet); capture_refused — Heilo hat den Anruf absichtlich nicht aufgezeichnet (dein Tarif oder die Testphase umfasst keine Aufzeichnung, oder die Nummer steht auf der Liste „Nicht aufzeichnen“); no_speech — die Aufnahme war zu kurz für eine Nachricht (drei Sekunden oder weniger); not_transcribed — es gibt eine Aufnahme, aber kein brauchbares Transkript. Ob jemand abgenommen hat, zeigt answered. Neue Werte können hinzukommen.
has_recordingbooleantrue, wenn eine Aufnahme dieses Anrufs existiert; ein API-Schlüssel mit dem Scope read.recordings erhält über GET /calls/:id/recording-url einen Link dazu.
answeredbooleantrue, wenn der Anruf durchgestellt und angenommen wurde, zum Beispiel ein Gespräch, das Heilo nicht aufgezeichnet hat; false, wenn niemand abgenommen hat. Lege einen Rückruf nur an, wenn der Wert false ist.
call.missed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.missed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "customer_phone_e164": "+447700900123",
    "customer_phone_national": "07700 900123",
    "company_phone_e164": "+48222630000",
    "call_created_at": "2026-09-08T10:00:00Z",
    "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "no_recording",
    "has_recording": false,
    "answered": false
  }
}
call.outbound.attemptedWird gesendet, wenn ein ausgehender Wählversuch einen Endzustand erreicht — auch bei Fehlschlägen. completed bedeutet, dass der Anruf zustande kam und normal endete; Aufzeichnung und Transkript folgen als separate Ereignisse.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
agent_user_idstring (uuid)ID des Heilo-Nutzers, der den Anruf gestartet hat.
customer_phonestringDie gewählte Kundennummer.
customer_phone_e164stringKundennummer zum CRM-Kontaktabgleich; null, falls in call.completed nicht verfügbar.
outbound_lifecycle'completed' | 'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate'Endzustand, der das Ereignis ausgelöst hat; completed bedeutet, dass der Anruf zustande kam und normal endete.
durationnumber | nullGesprächsdauer in Sekunden; null, wenn der Anruf beim Aufbau scheiterte oder die Dauer noch nicht bekannt ist.
attempted_atstring (ISO 8601)Zeitpunkt der Ereignis-Erzeugung (ISO 8601).
has_recordingbooleantrue nur, wenn outbound_lifecycle completed ist und der Anruf nicht im Modus no_recording lief — die Aufzeichnung folgt dann als call.recording.ready.
call.outbound.attempted
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.outbound.attempted",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agent_user_id": "2ce127a0-c621-483d-b576-e68f69d95e84",
    "customer_phone": "+447700900123",
    "customer_phone_e164": "+447700900123",
    "outbound_lifecycle": "completed",
    "duration": 95,
    "attempted_at": "2026-09-08T10:00:00Z",
    "has_recording": true
  }
}
call.recording.readyWird gesendet, wenn die Aufzeichnungsdatei verfügbar ist. Verwenden Sie es, um die Audiodatei abzurufen oder zu archivieren.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
recording_urlstring | nullLink zur Aufzeichnung, 7 Tage gültig; in seltenen Fällen null, wenn der Link nicht erzeugt werden konnte. Nach Ablauf holen Sie einen frischen Link über GET /calls/:id/recording-url.
durationnumber | nullDauer in Sekunden; null, wenn noch nicht bekannt.
call.recording.ready
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.recording.ready",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
    "duration": 87
  }
}
call.transcribedWird im selben Verarbeitungslauf wie call.completed gesendet — enthält nur das Transkript, ohne Anrufdaten und ohne Aufzeichnungslink.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
transcript_originalstring | nullRohes, wörtliches Transkript; null, wenn nicht verfügbar.
transcript_processedobjectVerarbeitete Anrufanalyse — siehe die transcript_processed-Feldübersicht in diesem Abschnitt.
outcomestring | nullErgebniscode zum Zeitpunkt, an dem das Ereignis gebaut wurde (siehe Ergebniscodes unten); null, wenn niemand eines gesetzt hat. Der Schlüssel fehlt bei einem Replay eines älteren Ereignisses oder wenn Heilo ihn nicht lesen konnte. Ein späteres call.outcome.changed hat Vorrang.
outcome_source'ai' | 'user' | nullWer das Ergebnis gesetzt hat: ai (von der Analyse gewählt), user (von einer Person gewählt oder bestätigt) oder null (niemand). Fehlt immer, wenn outcome fehlt.
call.transcribed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.transcribed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
    "transcript_processed": {
      "caller_name": "Alicja Testowa",
      "counterparty_name": null,
      "counterparty_email": null,
      "caller_location": "Warszawa, Mokotów",
      "client_address": "ul. Przykładowa 10",
      "client_city": "Warszawa",
      "client_country": "Poland",
      "service_needed": "Tynki gipsowe w mieszkaniu 65m²",
      "services_match": true,
      "preferred_date": "w przyszłym tygodniu",
      "additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
      "lead_score": 7,
      "summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
      "subject": "Wycena tynków — Warszawa, 65 m²",
      "detected_language": "pl"
    },
    "outcome": "quote_to_send",
    "outcome_source": "ai"
  }
}
call.failedWird gesendet, wenn ein ausgehender Anruf nicht zustande kam (keine Antwort, besetzt, Fehler beim Aufbau). Betrifft nur ausgehende Anrufe. Meist lohnt sich kein neuer Lead — protokollieren Sie stattdessen einen Kontaktversuch.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
outbound_lifecycle'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate'Welche Phase des ausgehenden Anrufs fehlgeschlagen ist.
failure_reasonstring | nullMaschinenlesbarer Fehlercode (z. B. customer_busy, agent_no_confirmation oder carrier_rejected, wenn der Netzbetreiber den Anruf zum Telefon des Vertriebsmitarbeiters abgelehnt hat); kann null sein.
call.failed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.failed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "outbound_lifecycle": "customer_no_answer",
    "failure_reason": "customer_busy"
  }
}
call.outbound.lifecycle_repairedWird gesendet, wenn Heilo den Zustand eines ausgehenden Anrufs nachträglich korrigiert (eine späte Rückmeldung des Anbieters hat bestätigt, dass der Anruf doch zustande kam). Aktualisieren Sie den Anrufzustand auf Ihrer Seite.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
previous_lifecycle'agent_only'Zustand vor der Korrektur; derzeit immer agent_only.
new_lifecycle'completed'Zustand nach der Korrektur; derzeit immer completed.
repaired_atstring (ISO 8601)Zeitpunkt der Korrektur (ISO 8601).
call.outbound.lifecycle_repaired
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.outbound.lifecycle_repaired",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "previous_lifecycle": "agent_only",
    "new_lifecycle": "completed",
    "repaired_at": "2026-09-08T10:00:00Z"
  }
}
call.deletion_scheduledDSGVO Art. 17: Der Anruf ist zur Löschung vorgemerkt. Ihr CRM sollte die Aufzeichnung nicht mehr verwenden und sich auf die Löschung der Daten vorbereiten. Sie werden über einen Anruf nur informiert, wenn Heilo einen Nachweis hat, dass dessen Inhalt Ihren Endpunkt erreicht haben könnte. Ein Abonnement allein auf die Löschereignisse macht Sie nicht zum Empfänger — es gibt nichts zu löschen, wenn Sie nie etwas erhalten haben.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
pending_deletion_atstring (ISO 8601)Wann die Daten endgültig gelöscht werden (ISO 8601).
reason'consent_not_asked' | 'consent_withdrawn' | 'retention_expired' | 'user_erasure'Grund für die geplante Löschung.
call.deletion_scheduled
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.deletion_scheduled",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pending_deletion_at": "2026-09-09T10:00:00Z",
    "reason": "retention_expired"
  }
}
call.recording.deletedDSGVO: Die Aufzeichnung wurde gelöscht — recording_url gibt 410 zurück. Entfernen oder deaktivieren Sie den Aufzeichnungslink auf Ihrer Seite. Ist `reason` etwas anderes als `retention_expired`, wurden auch Transkript, Zusammenfassung, die aus dem Gespräch gewonnenen Angaben und die Gesprächsnotizen gelöscht — löschen Sie diese bei sich ebenfalls. In den Papierkorb verschobene Anrufe kommen 30 Tage danach als dieses Ereignis mit dem Grund `user_erasure` an. Sie werden über einen Anruf nur informiert, wenn Heilo einen Nachweis hat, dass dessen Inhalt Ihren Endpunkt erreicht haben könnte; dies ist also keine vollständige Übersicht aller Löschungen in Ihrer Organisation. Ein 2xx von Ihnen bedeutet, dass die Anweisung angekommen ist, niemals dass die Kopie gelöscht wurde.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
reasonstring | nullBeim Planen der Löschung erfasster Grund; kann null sein.
recording_sidstring | nullTwilio-Aufzeichnungs-ID; null, wenn sie nicht ermittelt werden konnte.
deletion_kind'hard_deleted' | 'twilio_404'hard_deleted = von Heilo gelöscht; twilio_404 = die Datei war auf Twilio-Seite bereits verschwunden.
deleted_atstring (ISO 8601)Zeitpunkt der Löschung der Aufzeichnung (ISO 8601).
call.recording.deleted
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.recording.deleted",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "user_erasure",
    "recording_sid": null,
    "deletion_kind": "twilio_404",
    "deleted_at": "2026-09-08T10:00:00Z"
  }
}
call.followup_email.draftedWird gesendet, nachdem ein beidseitiges Gespräch verarbeitet wurde und Heilo aus den Absprachen einen Follow-up-E-Mail-Entwurf erstellt hat. Nicht bei Voicemail und nicht, wenn kein Entwurf erstellt werden konnte. Heilo sendet diese E-Mail NIEMALS an den Anrufer — der Entwurf ist für Ihren Vertriebsmitarbeiter zum Prüfen und Versenden.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
subjectstringE-Mail-Betreff, fertig zum Einfügen.
bodystringE-Mail-Text als reiner Text, OHNE Signatur — die Signatur fügt der Mitarbeiter beim Senden hinzu.
languagestringSprache des Entwurfs: die erkannte Gesprächssprache, ersatzweise die in Heilo eingestellte Kontosprache (keine Einstellung pro Nummer).
call.followup_email.drafted
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.followup_email.drafted",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "subject": "Oferta po rozmowie",
    "body": "Dzień dobry, przesyłam ustalenia naszej rozmowy.",
    "language": "pl"
  }
}
call.outcome.changedWird gesendet, sobald sich das Ergebnis eines Anrufs ändert: Jemand wählt es in Heilo aus, ändert, bestätigt oder entfernt es, oder eine erneute Analyse ändert das Ergebnis, das Heilo vorher gewählt hat. Das Ergebnis, das Heilo bei der ersten Analyse der Aufnahme wählt, bekommt kein eigenes Ereignis; es kommt in call.completed und call.transcribed. Ein Ergebnis, das erst bei einer späteren erneuten Analyse zum ersten Mal gewählt wird, löst call.outcome.changed aus. Wird nicht für Anrufe im Papierkorb oder mit geplanter Löschung gesendet. Änderungsereignisse haben Vorrang vor dem Ergebnis in call.completed und call.transcribed; sortiere sie nach data.changed_at.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
outcomestring | nullDas Ergebnis nach der Änderung; null, wenn es entfernt oder zurückgezogen wurde.
outcome_source'ai' | 'user' | nullWer es nach der Änderung gesetzt hat: ai, user oder null. Ein leeres Ergebnis mit user bedeutet, dass eine Person es entfernt hat; ein leeres Ergebnis mit null bedeutet, dass die Analyse ihre Wahl zurückgezogen hat.
previous_outcomestring | nullDas Ergebnis vor der Änderung; null, wenn es keines gab.
previous_outcome_source'ai' | 'user' | nullWer das vorherige Ergebnis gesetzt hatte: ai, user oder null.
changed_atstring (ISO 8601)Wann die Änderung gespeichert wurde (ISO 8601). Sortiere Änderungsereignisse danach: Das mit dem spätesten changed_at ist aktuell. Es ist nicht das created_at des Umschlags.
call.outcome.changed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.outcome.changed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "outcome": "booking",
    "outcome_source": "user",
    "previous_outcome": "quote_to_send",
    "previous_outcome_source": "ai",
    "changed_at": "2026-09-08T10:05:00Z"
  }
}
call.user_notes.changedWird gesendet, wenn sich die Einträge ändern, die Personen in Heilo zu einem Gespräch geschrieben haben („Gesprächsnotizen“): Jemand fügt einen Eintrag hinzu, bearbeitet oder löscht ihn. data.notes ist die GANZE aktuelle Liste, keine Differenz; Ihr CRM ersetzt also seine Kopie, statt sie zusammenzuführen. Das Ereignis geht etwa fünf Minuten nach der letzten Änderung hinaus (bei Einträgen, die während eines Gesprächs getippt wurden: etwa fünf Minuten nach dem Gespräch) und nie öfter als einmal alle fünf Minuten pro Gespräch. data.revision wächst mit jeder Änderung; verwerfen Sie eine Liste, deren revision nicht höher ist als die, die Sie bereits haben (ein manueller erneuter Versand sendet eine ältere Liste noch einmal). Wird nicht gesendet für Gespräche im Papierkorb oder mit geplanter Löschung.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
revisionintegerZähler, der mit jeder Änderung der Einträge zum Gespräch wächst. Merken Sie sich die höchste revision pro Gespräch und verwerfen Sie jede Liste, deren revision nicht höher ist; ein manueller erneuter Versand oder ein Replay liefert eine ältere Liste.
changed_atstring (ISO 8601)Wann Heilo diese Liste erstellt hat (ISO 8601). Nicht das created_at des Umschlags und nicht der Zeitpunkt, zu dem jemand einen Eintrag bearbeitet hat.
notesobject[]Die ganze aktuelle Liste der Einträge, älteste zuerst, höchstens 200; leer, wenn der letzte Eintrag gelöscht wurde. Ersetzen Sie Ihre Kopie damit.
notes[].idstring (uuid)Kennung des Eintrags; bleibt bei einer Textänderung gleich.
notes[].bodystringDer Text des Eintrags, 1 bis 2000 Zeichen.
notes[].source'live' | 'after' | 'legacy'live: während des Gesprächs auf dem Gesprächsbildschirm getippt. after: nachträglich in Heilo hinzugefügt. legacy: die einzelne Gesprächsnotiz von vor dem 28.10.2026, in die Einträge übernommen. Neue Werte können hinzukommen.
notes[].author.idstring (uuid) | nullDer Heilo-Nutzer, der den Eintrag geschrieben hat. Null bei einem legacy-Eintrag oder wenn dieses Konto gelöscht wurde.
notes[].author.namestring | nullDer vollständige Name des Autors aus seinem Heilo-Profil; null, wenn das Profil keinen hat. Nie eine E-Mail-Adresse. Eine spätere Namensänderung erscheint in der nächsten Liste, ohne eigenes Ereignis.
notes[].noted_atstring (ISO 8601)Wann die Person den Eintrag geschrieben hat (ISO 8601); bei einem live-Eintrag der Moment während des Gesprächs.
notes[].recording_offset_secondsinteger | nullSekunden ab Beginn der Aufzeichnung, nur für einen während des Gesprächs innerhalb der Aufzeichnung getippten Eintrag; sonst null.
notes[].created_atstring (ISO 8601)Wann der Eintrag gespeichert wurde (ISO 8601).
notes[].updated_atstring (ISO 8601)Letzte Bearbeitung des Textes (ISO 8601).
call.user_notes.changed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.user_notes.changed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "revision": 3,
    "changed_at": "2026-09-08T10:12:00Z",
    "notes": [
      {
        "id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "body": "Klient prosi o telefon po 10:00.",
        "source": "live",
        "author": {
          "id": "2ce127a0-c621-483d-b576-e68f69d95e84",
          "name": "Anna Nowak"
        },
        "noted_at": "2026-09-08T10:01:12Z",
        "recording_offset_seconds": 72,
        "created_at": "2026-09-08T10:01:12Z",
        "updated_at": "2026-09-08T10:01:12Z"
      }
    ]
  }
}
call.tracker.matchedWird gesendet, wenn mindestens ein konfigurierter Keyword-Tracker zum verarbeiteten Transkript passt. Treffer enthalten Begriffe und Auszüge; fehlende Auszüge ergeben ein leeres Array.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
matchesobject[]In diesem Anruf gefundene Tracker.
matches[].tracker_idstring (uuid)Kennung des konfigurierten Trackers.
matches[].namestringTrackername.
matches[].matched_termsstring[]Gefundene Begriffe.
matches[].excerptsstring[]Transkriptauszüge; kann leer sein.
call.tracker.matched
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.tracker.matched",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "matches": [
      {
        "tracker_id": "cd794362-6117-44d1-b487-c5e7e1ea9082",
        "name": "Oferta",
        "matched_terms": [
          "ofertę"
        ],
        "excerpts": [
          "Proszę o ofertę w przyszłym tygodniu."
        ]
      }
    ]
  }
}
contact.createdWird gesendet, wenn in Heilo ein neuer Kontakt angelegt wird. data.contact ist eine vollständige Momentaufnahme des neuen Kontakts; Notizen und Tags sind nicht enthalten.
FeldTypBeschreibung
contactobjectVollständige Momentaufnahme des neuen Kontakts (Felder unten).
contact.idstring (uuid)Kontakt-ID in Heilo.
contact.phonestringTelefonnummer des Kontakts.
contact.first_namestring | nullnull, wenn nicht angegeben.
contact.last_namestring | nullnull, wenn nicht angegeben.
contact.emailstring | nullnull, wenn nicht angegeben.
contact.companystring | nullnull, wenn nicht angegeben.
contact.created
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "contact.created",
  "resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "contact": {
      "id": "86c68698-d54c-43e7-bbbc-328499b98d12",
      "phone": "+447700900123",
      "first_name": "Alicja",
      "last_name": "Testowa",
      "email": "alicja@example.com",
      "company": null
    }
  }
}
contact.updatedWird gesendet, wenn ein Kontakt bearbeitet wird. Anders als bei contact.created ist dies keine Momentaufnahme: data.diff enthält nur die geänderten Felder.
FeldTypBeschreibung
contact_idstring (uuid)ID des aktualisierten Kontakts.
diffobject (partial)Nur die geänderten Felder — Schlüssel, die in diff fehlen, wurden nicht geändert.
contact.updated
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "contact.updated",
  "resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "contact_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
    "diff": {
      "company": "Example",
      "notes": "Oddzwonić",
      "tags": [
        "oferta"
      ]
    }
  }
}

Mögliche Schlüssel in diff: first_name, last_name, email, phone, company, notes, tags

webhook.testWird nur beim Klick auf Test am Abonnement gesendet. resource_id ist die Abonnement-ID, nicht die Anruf-ID. data enthält synthetische call.completed-Daten und die drei unten beschriebenen Testmarker. Dies bestätigt keine Verfügbarkeit echter Audiodaten.
FeldTypBeschreibung
call_idstring (uuid)Anruf-ID in Heilo. Bei geschäftlichen Anrufereignissen identisch mit resource_id; bei webhook.test eine synthetische Anruf-ID.
direction'inbound' | 'outbound'Anrufrichtung.
caller_phonestring | nullGespeicherte Anrufernummer; null, falls in call.completed nicht verfügbar.
customer_phone_e164string | nullKundennummer zum CRM-Kontaktabgleich; null, falls in call.completed nicht verfügbar.
customer_phone_nationalstring | nullDieselbe Kundennummer im nationalen Format, direkt für ein CRM-Telefonfeld; null, wenn der gespeicherte Wert keine nutzbare Nummer ist, etwa bei unterdrückter Rufnummer.
company_phone_e164string | nullDie Nummer, über die dieses Gespräch einging oder ausging. In der Regel Ihre Heilo-Nummer; bei einer Weiterleitung Ihre eigene Nummer, die das Gespräch weitergeleitet hat. Damit lassen sich Notizen zuordnen, wenn Sie mehrere Nummern nutzen; null, wenn nicht erfasst.
call_created_atstring (ISO 8601) | nullWann das Gespräch in Heilo erfasst wurde (ISO 8601). Nicht identisch mit created_at im Umschlag, das den Versandzeitpunkt angibt und bei einem reparierten Ereignis Tage später liegen kann.
app_urlstring | nullDauerhafter Link zum Gespräch in Heilo. Anders als recording_url läuft er nicht ab und kann im CRM-Datensatz bleiben. Zum Öffnen ist eine Heilo-Anmeldung nötig.
durationnumberLänge der Aufzeichnung in Sekunden.
recording_urlstring | nullLink zur Aufzeichnung, 7 Tage gültig; null, wenn die Aufzeichnung zum Verarbeitungszeitpunkt noch nicht gespeichert war. Nach Ablauf holen Sie einen frischen Link über GET /calls/:id/recording-url.
transcript_processedobjectVerarbeitete Anrufanalyse — siehe die transcript_processed-Feldübersicht in diesem Abschnitt.
transcript_originalstring | nullRohes, wörtliches Transkript; null, wenn nicht verfügbar.
outcomestring | nullErgebniscode zum Zeitpunkt, an dem das Ereignis gebaut wurde (siehe Ergebniscodes unten); null, wenn niemand eines gesetzt hat. Der Schlüssel fehlt bei einem Replay eines älteren Ereignisses oder wenn Heilo ihn nicht lesen konnte. Ein späteres call.outcome.changed hat Vorrang.
outcome_source'ai' | 'user' | nullWer das Ergebnis gesetzt hat: ai (von der Analyse gewählt), user (von einer Person gewählt oder bestätigt) oder null (niemand). Fehlt immer, wenn outcome fehlt.
_testtrueImmer true — unterscheidet die Testnachricht von echten Ereignissen.
_messagestringLesbarer Hinweis, dass es sich um einen Test handelt.
_sent_atstring (ISO 8601)Zeitpunkt des Testversands (ISO 8601).
webhook.test
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "webhook.test",
  "resource_id": "c2d38cc8-bc1d-4336-91ea-51b8a549a882",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "caller_phone": "+447700900123",
    "customer_phone_e164": "+447700900123",
    "customer_phone_national": "07700 900123",
    "company_phone_e164": "+48222630000",
    "call_created_at": "2026-09-08T10:00:00Z",
    "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "duration": 87,
    "recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
    "transcript_processed": {
      "caller_name": "Alicja Testowa",
      "counterparty_name": null,
      "counterparty_email": null,
      "caller_location": "Warszawa, Mokotów",
      "client_address": "ul. Przykładowa 10",
      "client_city": "Warszawa",
      "client_country": "Poland",
      "service_needed": "Tynki gipsowe w mieszkaniu 65m²",
      "services_match": true,
      "preferred_date": "w przyszłym tygodniu",
      "additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
      "lead_score": 7,
      "summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
      "subject": "Wycena tynków — Warszawa, 65 m²",
      "detected_language": "pl"
    },
    "transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
    "outcome": "quote_to_send",
    "outcome_source": "ai",
    "_test": true,
    "_message": "Synthetic webhook test; do not create CRM records.",
    "_sent_at": "2026-09-08T10:00:00Z"
  }
}

transcript_processed — Feldübersicht

Der stabile Teil der Felder, auf den Sie sich beim Mapping in ein CRM verlassen können. Jedes Feld ist optional — es ist null, wenn das Gespräch diese Information nicht enthielt.

FeldTypBeschreibung
caller_namestring | nullName des Anrufers, sofern genannt.
summarystring | nullKurze Zusammenfassung des Anrufs.
subjectstring | nullEinzeiliger Titel des Anrufs (bis 80 Zeichen).
service_neededstring | nullWorum der Anrufer gebeten hat.
services_matchboolean | nullOb die Anfrage zu den von Ihnen angebotenen Leistungen passt.
lead_scorenumber | null (1–10)Einschätzung der Lead-Qualität von 1 bis 10, oder null, wenn die KI keine abgegeben hat.
preferred_datestring | nullVom Anrufer genannter Termin, sofern vorhanden.
client_citystring | nullStadt, sofern erwähnt.
client_addressstring | nullAdresse, sofern erwähnt.
additional_detailsstring | nullZusätzlicher Kontext aus dem Anruf.

Felder, die auftreten können

FeldTypBeschreibung
caller_locationstring | nullIm Gespräch erkannter geografischer Bezug.
client_countrystring | nullLand, sofern erwähnt.
counterparty_namestring | nullName der Gegenseite — nur bei ausgehenden Anrufen und bei Live-Gesprächen, zu denen Heilo hinzugefügt wurde.
counterparty_emailstring | nullE-Mail-Adresse des Kunden, wie sie im Gespräch genannt und mit dem Transkript abgeglichen wurde — nur bei Live-Gesprächen, zu denen Heilo hinzugefügt wurde.
detected_languagestringSprachcode des Gesprächs (z. B. pl); der Schlüssel kann ganz fehlen.
proposal_itemsobject[] | nullAus dem Anruf abgeleitete Vorschläge für Folgeaufgaben und Entscheidungen.

Die Analyse kann zusätzliche Felder enthalten — behandeln Sie unbekannte Felder als optional und setzen Sie ihr Vorhandensein nie voraus.

Roadmap (v1.1+)

Endpunkte, die für kommende v1.X-Releases geplant sind. Keine feste Zusage — die Richtung hängt vom Feedback ab.

  • GET /contacts — Kontakte auflisten
  • POST /contacts — Kontakt erstellen (Synchronisierung vom CRM nach Heilo)
  • POST /calls — einen ausgehenden Anruf über Ihre Heilo-Nummer starten; er wird aufgezeichnet, transkribiert und wie jeder andere Anruf an Ihr CRM übergeben

Brauchen Sie einen Endpunkt? Schreiben Sie mit Ihrem Anwendungsfall an support@heilo.io — wir priorisieren die Roadmap nach tatsächlichem Bedarf.

Roadmap (v1.1+)

Brauchen Sie einen Endpunkt? Schreiben Sie mit Ihrem Anwendungsfall an support@heilo.io — wir priorisieren die Roadmap nach tatsächlichem Bedarf.

Schlüssel und Webhooks im Panel verwalten

Nach der Anmeldung generieren Sie API-Schlüssel, fügen Webhook-Abonnements hinzu und sehen das Zustellungsprotokoll ein.