Zum Inhalt springe

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.recordingsErstellt über `GET /calls/:id/recording-url` en Link zum Audio vom ene Aaruef. Getrennt vo `read.calls`, wil Audio en anderi Iwilligung isch als Metadate — en bestehende Schlüssel überchunnt en nöd, du machsch en neue mit usdrücklichem Ufnahmszuegriff.
read.transcriptsFügt `GET /calls/:id` de Transkripttext hinzue: `transcript_original`, `transcript_edited` und `transcript_edited_at`. Getrennt vo `read.calls`, will d Wörter vomene Gspräch en anderi Iwilligung sind als Metadate — en bestehende Schlüssel überchunnt si nöd, me macht en neue Schlüssel mit usdrücklichem Transkriptzuegriff. Ohni si fähled die Fälder, und dr Ufruef antwortet wiiterhin mit 200. Brucht zuesätzlich `read.calls`: en Schlüssel nume mit `read.transcripts` überchunnt 403, und s Erstelle wird mit 400 abgwise.
write.calls, read.contacts, write.contacts, manage.webhooks, manage.api_keysReserviert für plant API-Endpunkt. Mit ene cha kei neue Schlüssel erstellt wärde (400 BAD_REQUEST). En ältere Schlüssel cha na eine vo ene ha, und er git nüt.

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, auch nicht neue Felder in den Webhook-Payloads.

Abwärtskompatibel: neue Antwortfelder, neue Felder in den 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

Jedi erfolgriichi Antwort enthaltet X-RateLimit-Limit (s Stundelimit vom Schlüssel), X-RateLimit-Remaining (wivill Aafrage dr Schlüssel i dere Stund na het) und X-RateLimit-Reset (wänn dr Zähler zruggsetzt wird, ISO 8601). Bi Überschriitig antworte mir mit 429 und em Header Retry-After (Sekunde 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 ausserhalb 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_UNAVAILABLEEn Teil vom Dienst, wo dr Ufruef bruucht, isch nöd verfüegbar (zum Bispiil chönd grad kei Link zu Ufzeichnige erstellt wärde) — mit Backoff widerhole
503WEBHOOK_ACTIVATION_LOCKEDS Iischalte vo Webhook-Abonnement isch für e Migration aagha; bestehendi Abonnement lauffed wiiter — spöter nomal probiere
422SUBSCRIPTION_LIMITD Organisation het ires Limit a Webhook-Abonnement erreicht (HTTP 422) — zerscht eis ungnutzts lösche

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

En Fähler cha au error.details mit Iizelheite enthalte, zum Bispiil d Fälder, wo d Validierig nöd bstande händ; s Fäld cha fähle. Stabil isch dr 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.

D Liste fangt mit em neueschte Gspräch aa (created_at absteigend) und wird sitewiis gliferet; es Gspräch, wo während em Blättere ichunnt, verschiebt d Zile. Entdoppled nach call_id und lised d erscht Site nomal, zum ufhole. Das isch kei Export vo dr ganze 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
phonestringd Chundenummere vom Gspröch, mit Ländervorwahl; Läärschläg, Bindestrich und s füehrende + 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.

A dem Endpunkt enthaltet s Analyseobjekt transcript_processed summary, service_needed, caller_name und followup_email, und au subject, lead_score (1–10, Schätzig vom Modell), detected_language und client_city: di gliiche Wärt, wo dr Webhook call.completed schickt. S Fäld, wo d Analyse nöd erzügt het, isch null. has_recording zeigt, öb Audio gspeicheret isch; s Audio sälber chunnt vo GET /calls/:id/recording-url mit em Scope read.recordings.

Mit em Scope read.transcripts enthaltet d Antwort zuesätzlich transcript_original (null, wänn s Gspräch ken bruchbari Transkription het: na i Verarbeitig, fählgschlage oder kei Sprach), transcript_edited und transcript_edited_at (null, wänn niemer s bearbeitet het). Ohni dr Scope fähled die drü Fälder (nöd null), und d Antwort isch wiiterhin 200.

D Antwort enthaltet zuedem user_notes: d Iiträg, wo Lüüt i Heilo zum Gspräch gschribe händ („Gsprächsnotize“), de ältscht zerscht, höchschtens 200, es leers Array, wenn es kei hät. De Listen-Endpunkt GET /calls liferet si nöd. S Bispiil isch kürzt; di andere Fälder sind di glichen wie i de Liste. Um über Änderige vo de Iiträg informiert z werde, abonniered 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"
  }
}

Es frisch signierts Link zum Audio vom Aaruef, 15 Minute gültig. Es isch e Download-Bereichtigung mit eme Ablauf, kei dauerhafti Referenz: speicher d `call_id` und frag nomal, wil en Link, wo im CRM-Fäld liit, i weniger als ere Stund tot isch. De Link im Webhook `call.recording.ready` isch sibe Täg signiert — über dää Endpunkt chunnsch du nachher as Audio.

  • 200 — de Link und de Moment, wo er ufhört z funktioniere.
  • 409 `RECORDING_NOT_READY` — de Aaruef ghört dir und s Audio isch no nöd da. Frag glii nomal.
  • 409 `RECORDING_WITHHELD` — de Aaruef isch im Abfall oder zum Lösche vorgmerkt. En Aaruef im Abfall cha de Kund 30 Täg lang widerherstelle, also frag wiiter, statt d Ufnahm bi dir abzschriibe; en Aaruef mit Ufnahm wird 30 Täg nachem Verschiebe in Abfall glöscht. E vorgmerkti Löschig lat sich nöd rückgängig mache: bruuch d Ufnahm nümme. I beidne Fäll bechunnsch du nach em Lösche 410.
  • 410 `RECORDING_DELETED` — d Ufnahm isch glöscht worde (Ufbewahrigsfrist, de Abfall nach 30 Täg oder e Löschafrog), es isch nöd meh z rette. Hör uf z frage und uf z queue.
  • 410 `RECORDING_NOT_CAPTURED` — dä usgehend Aaruef isch nie ufgno worde und es wird nie e Ufnahm dafür gäh: s Capture-Gate hät en bim Start abglehnt, er isch im Modus no_recording gloffe oder hät ohni Gspröch ufghört. Hör uf z frage — es gits kei Grund zum nomal probiere. En iigehende Aaruef, wo d Ufnahm abglehnt worde isch, git wiiterhin 409, will no e Ufnahm cho cha.

D Antwort chunnt mit `Cache-Control: no-store`, wil de Body e Bereichtigung treit. D Bereichtigung wird bim Abhole vo de Datei nomal prüeft, nöd nu bim Erstelle vom Link — en zwüschedure glöschte Aaruef isch sofort nüme läsbar.

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

Wedr d Gsprächsliste na d Details liferet e Ufzeichnigsdatei oder en Link; d Details säged nume, öb e Ufzeichnig existiert (has_recording). Dr Link zur Ufzeichnig überchömed Si im Webhook, und nach sim Abluf über `GET /calls/:id/recording-url`. Ufzeichnige chönd nach de Regle zu Ufbewahrig und DSGVO glöscht wärde.

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
Gsprächsergäbnis und wer es gsetzt hetjaja
Gsprächsnotize (REST: nur i GET /calls/:id)jaja
Zusammenfassung, Anrufername, Kundenbedarfjaja
Der Rest der Analyse: Stadt, Adresse, Lead-Score, Wunschtermin, Spracheteilwiis: GET /calls/:id liefered Stadt, Lead-Score und Sproch; Adrässe und Wunschtermin chömed nume us em Webhookja
Das wortwörtliche Transkriptja, GET /calls/:id mit read.transcriptsja
Aufnahme-Linkja, über /calls/:id/recording-urlja, 7 Tage gültig

Drus folgt d praktisch Regle: Dr Webhook liferet alles im Momänt vo dr Verarbeitig, REST git nachher d Details vomene einzelne Gspräch, mit dr erwiiterete Analyse und, mit read.transcripts, dr Transkription. D Ufzeichnig holt men uf eigeni Wiis — frög /calls/:id/recording-url nach emene früsche 15-Minute-Link, statt dr sibetägig us em Payload z spychere.

Spezifikation und en echti Aafrog

Die glyche vier Operatione, für Maschine gschribe: OpenAPI 3.1. In Postman oder Insomnia importiere oder en Client i dyner Sprach generiere.

OpenAPI 3.1 abelade

Spezifikation und en echti Aafrog

Schick vo do us ei Aafrog und prüef dyn Schlüssel, bevor du Code schrybsch.

Das rüeft di echti API mit dym echte Schlüssel uf und git dyni eigene Date zrugg. De Schlüssel bliibt i dem Browser-Tab — mir speichered en 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.

D Endpunktadrässe muess https sii, öffentlich erreichbar und dörf nöd uf e private oder interni Adrässe zeige (localhost, 10.x, 192.168.x und ähnlichi). Zum Teschte vom eigene Computer machet Si en über en öffentliche Tunnel erreichbar. Endpunkt wärded nume under Iistellige → Integratione aaglegt; kei API-Ufruef leit eine aa.

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 einschliesslich 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 vo dr manuelle Aktion Test gschickt und het data._test = true. Es lauft dur di gliich Zuestellwarteschlange wie echti Ereignis, cha also en Momänt nach em Klick ichoo, und sis Ergäbnis erschiint als Status im Zuestellprotokoll. Bruched Si s zum d Fälder zuordne und schlüsset Si s denn vo dr gschäftliche Verarbeitig us. Dr separat Aktivierigs-Handshake isch 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ürs Follow-up parat
call.outcome.changedGsprächsergäbnis gsetzt oder gänderet
call.user_notes.changedGsprächsnotize ergänzt, gänderet oder glöscht
call.tracker.matchedTracker troffe
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 (einschliesslich 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 | nullErgäbnis-Code zum Ziitpunkt, wo s Event ufbaut worde isch (lueg d Ergäbnis-Codes unde); null, wenn niemer eis gsetzt het. De Schlüssel fählt bi me Replay vomene ältere Event oder wenn Heilo en nöd het chönne läse. E spätere call.outcome.changed het Vorrang.
outcome_source'ai' | 'user' | nullWer s Ergäbnis gsetzt het: ai (vo de Analyse gwählt), user (vonere Person gwählt oder bestätigt) oder null (niemer). Fählt immer, wenn outcome fählt.

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

Gsprächsergäbnis

outcome isch eine vo de Codes unde oder null, wenn niemer eis gsetzt het. outcome_source seit, wer es gsetzt het: ai oder user. REST git beidi Fälder bi jedem Gspräch zrugg; call.completed und call.transcribed träged si ufere oberschte Ebeni vo data; call.outcome.changed meldet jedi spätere Änderig. Es chönd neui Codes derzue cho, bhandle en unbekannte Wert also als zuesätzlichi Information und nöd als Fehler.

CodeBedütig
bookingE Buechig, en Bsuech oder en Termin isch abgmacht worde.
cancellation_or_rescheduleDe Aaruefer het abgsait oder bitet um en neue Termin.
information_requestDe Aaruefer het nach Informatione gfrögt.
quote_to_sendDe Aaruefer wartet uf e Offerte.
awaiting_customer_decisionDe Chund überlegt no und meldet si.
deal_wonDe Chund het im Gspröch emne Chauf oder ere Bstellig zuegstimmt oder s Agebot agnoh. Start e „gwunne“-Automatisierig i dim CRM nume, wenn outcome_source user isch.
callback_scheduledEn witere Kontakt isch abgmacht worde.
not_interestedDe Aaruefer isch nöd interessiert.
spam_wrong_numberLeeri Nachricht, Spam oder falsch verbunde.
new_opportunityE neui Verchaufschance.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho
existing_deal_updateEs Update zumene bestehende Projekt.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho
follow_upEn Folgekontakt nach emene früechere Gspräch.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho
no_answerNiemer het abgnoh.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho
voicemailDe Aaruefer het e Sprachnachricht hinterlah.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho
supportE Support-Aafrag.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho
complaintE Reklamation.veraltet: wird nümme aabote, cha bi ältere Gspräch no vorcho

Weler Wert gilt

E call.outcome.changed-Event het Vorrang vor em Ergäbnis i call.completed und call.transcribed, i welere Reihefolg si au acho. Sortier Änderigs-Events nach data.changed_at, nie nach de Aachunftsziit oder em created_at vom Umschlag. REST git immer de aktuell Wert zrugg, demit holsch es verpasste Event nache.

data.outcome isch en Code us de Tabälle obe. Es isch nöd s gliiche wie transcript_processed.call_outcome, en Satz i Freitext us de Analyse.

Zapier und Make: De Test-Button schickt d Form vo call.completed. Für es Bispiil vo call.outcome.changed wähl bi irgend emene Gspräch i Heilo es Ergäbnis.

Gsprächsnotize (user_notes)

user_notes isch d Liste vo de Iiträg, wo Lüüt i Heilo zumene Gspräch gschribe händ („Gsprächsnotize“). REST liferet si nur i GET /calls/:id; call.user_notes.changed schickt die ganzi aktuelli Liste öppe föif Minute nach de letschte Änderig. De Autor isch de vollständig Name us em Heilo-Profil, nie e E-Mail-Adrässe.

Weli Liste gilt

Jedi Liste treit e revision, wo mit jedere Änderig wachst. Ersetzed Sie Ihri Kopie nur dur e Liste, wo ihri revision höcher isch als Ihri, und verwärfed Sie jedi anderi: En manuelle erneuti Versand liferet e ältteri Liste nomal. REST liferet immer die aktuelli Liste, drum holed Sie demit es verpasste Event nach.

source seit, woher en Iitrag stammt: live (während em Gspräch uf em Gsprächsbildschirm tippt), after (nachträglich ergänzt) oder legacy (die einzelni Gsprächsnotiz vo vor em 28.10.2026). Neui Wärt chönd derzue cho; behandled Sie en unbekannte Wert als optionali Informatione, nöd als Fehler. recording_offset_seconds isch nur für en live-Iitrag gsetzt, wo innerhalb vo de Ufnahm tippt worde isch.

Zapier und Make: D Schaltfläche Test schickt d Form vo call.completed. Für es Bispiil vo call.user_notes.changed ergänzed Sie i Heilo bi irgend emene Gspräch en Iitrag und warted föif Minute.

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 | nullErgäbnis-Code zum Ziitpunkt, wo s Event ufbaut worde isch (lueg d Ergäbnis-Codes unde); null, wenn niemer eis gsetzt het. De Schlüssel fählt bi me Replay vomene ältere Event oder wenn Heilo en nöd het chönne läse. E spätere call.outcome.changed het Vorrang.
outcome_source'ai' | 'user' | nullWer s Ergäbnis gsetzt het: ai (vo de Analyse gwählt), user (vonere Person gwählt oder bestätigt) oder null (niemer). Fählt immer, wenn outcome fählt.
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 gschickt, sobald sich s Ergäbnis vomene Gspräch ändert: Öpper wählt, ändert, bestätigt oder löscht s i Heilo, oder e neui Analyse ändert s Ergäbnis, wo Heilo vorhär gwählt het. S Ergäbnis, wo Heilo bi de erschte Analyse vo de Ufnahm wählt, überchunnt kei eigets Event; es chunnt i call.completed und call.transcribed. E Ergäbnis, wo erscht bi re spätere neue Analyse zum erschte Mal gwählt wird, schickt call.outcome.changed. Wird nöd gschickt für Gspräch im Papierchorb oder mit gplanter Löschig. Änderigs-Events händ Vorrang vor em Ergäbnis i call.completed und call.transcribed; sortier si 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 | nullS Ergäbnis nach de Änderig; null, wenn es glöscht oder zrugggzoge worde isch.
outcome_source'ai' | 'user' | nullWer es nach de Änderig gsetzt het: ai, user oder null. E leers Ergäbnis mit user heisst, e Person het es glöscht; e leers Ergäbnis mit null heisst, d Analyse het ihri Wahl zrugggzoge.
previous_outcomestring | nullS Ergäbnis vor de Änderig; null, wenn es keis gä het.
previous_outcome_source'ai' | 'user' | nullWer s vorig Ergäbnis gsetzt gha het: ai, user oder null.
changed_atstring (ISO 8601)Wänn d Änderig gspeicheret worde isch (ISO 8601). Sortier d Änderigs-Events dernoch: S mit em spätschte changed_at isch aktuell. Es isch nöd s created_at vom Umschlag.
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 gschickt, sobald sich d Iiträg ändered, wo Lüüt i Heilo zumene Gspräch gschribe händ („Gsprächsnotize“): Öpper ergänzt en Iitrag, bearbeitet ne oder löscht ne. data.notes isch die GANZI aktuelli Liste, kei Differänz; Ihres CRM ersetzt also sini Kopie, statt si zämezfüehre. S Event gaht öppe föif Minute nach de letschte Änderig use (bi Iiträg, wo während emene Gspräch tippt worde sind: öppe föif Minute nach em Gspräch) und nie öftrer als einisch alli föif Minute pro Gspräch. data.revision wachst mit jedere Änderig; verwärfed Sie e Liste, wo ihri revision nöd höcher isch als die, wo Sie scho händ (en manuelle erneuti Versand schickt e ältteri Liste nomal). Wird nöd gschickt für Gspräch im Papierchorb oder mit gplanter Löschig.
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, wo mit jedere Änderig vo de Iiträg zum Gspräch wachst. Merked Sie sich die höchscht revision pro Gspräch und verwärfed Sie jedi Liste, wo ihri revision nöd höcher isch; en manuelle erneuti Versand oder es Replay liferet e ältteri Liste.
changed_atstring (ISO 8601)Wänn Heilo die Liste ufbaut het (ISO 8601). Nöd s created_at vom Umschlag und nöd de Ziitpunkt, wo öpper en Iitrag bearbeitet het.
notesobject[]Die ganzi aktuelli Liste vo de Iiträg, de ältscht zerscht, höchschtens 200; leer, wenn de letscht Iitrag glöscht worde isch. Ersetzed Sie Ihri Kopie dermit.
notes[].idstring (uuid)Kennig vom Iitrag; blibt glich, wenn de Text bearbeitet wird.
notes[].bodystringDe Text vom Iitrag, 1 bis 2000 Zeiche.
notes[].source'live' | 'after' | 'legacy'live: während em Gspräch uf em Gsprächsbildschirm tippt. after: nachträglich i Heilo ergänzt. legacy: die einzelni Gsprächsnotiz vo vor em 28.10.2026, i d Iiträg übernah. Neui Wärt chönd derzue cho.
notes[].author.idstring (uuid) | nullDe Heilo-Nutzer, wo de Iitrag gschribe het. Null bi emene legacy-Iitrag oder wenn das Konto glöscht worde isch.
notes[].author.namestring | nullDe vollständig Name vom Autor us sim Heilo-Profil; null, wenn s Profil keine het. Nie e E-Mail-Adrässe. E spätere Namensänderig erschiint i de nächschte Liste, ohni eigets Event.
notes[].noted_atstring (ISO 8601)Wänn d Person en gschribe het (ISO 8601); bi emene live-Iitrag de Moment während em Gspräch.
notes[].recording_offset_secondsinteger | nullSekunde ab em Aafang vo de Ufnahm, nur für en Iitrag, wo während em Gspräch innerhalb vo de Ufnahm tippt worde isch; susch null.
notes[].created_atstring (ISO 8601)Wänn de Iitrag gspeicheret worde isch (ISO 8601).
notes[].updated_atstring (ISO 8601)Letschti Bearbeitig vom Text (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 | nullErgäbnis-Code zum Ziitpunkt, wo s Event ufbaut worde isch (lueg d Ergäbnis-Codes unde); null, wenn niemer eis gsetzt het. De Schlüssel fählt bi me Replay vomene ältere Event oder wenn Heilo en nöd het chönne läse. E spätere call.outcome.changed het Vorrang.
outcome_source'ai' | 'user' | nullWer s Ergäbnis gsetzt het: ai (vo de Analyse gwählt), user (vonere Person gwählt oder bestätigt) oder null (niemer). Fählt immer, wenn outcome fählt.
_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 vo de Gägesiite — nur bi usgehende Aarüef und bi Live-Gspröch, wo Heilo dezuegfüegt worde isch.
counterparty_emailstring | nullE-Mail-Adresse vom Chund, wie si im Gspröch gnännt und mit em Transkript abgliche worde isch — nur bi Live-Gspröch, wo Heilo dezuegfüegt worde isch.
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 übermittelt

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 verwalte

Nach der Anmeldig generieren Sie API-Schlüssel, fügen Webhook-Abonnemente hinzu und sehen das Zustelligsprotokoll ii.