API Reference v1

De snelste route om een CRM met Heilo te verbinden. De volledige API-referentie staat hieronder.

1. Stel een webhook-endpoint beschikbaar in uw CRM of middleware (zonder code: gebruik Zapier/Make — zie de handleiding hieronder).
2. Voeg een abonnement toe in Heilo (Instellingen → Integraties) voor call.completed (optioneel ook call.outbound.attempted).
3. Ontvang call.completed en verifieer de handtekening (Heilo-Signature-header, HMAC — zie hieronder).
4. Ontdubbel op event_id (heilo-event-id-header); data.call_id groepeert events van hetzelfde gesprek.
5. Map de velden naar uw CRM: vind/maak een contact op telefoonnummer, maak een lead/deal aan en koppel een activiteit/notitie (samenvatting + opnamekoppeling).

Geen code? De no-code verbindingshandleiding (Zapier/Make) leidt u er stap voor stap doorheen.

De publieke API gebruikt Bearer-tokens. Genereer een API-sleutel via de kaart "API-sleutels" op de pagina Integraties en stuur deze mee in de header:

Authorization: Bearer hk_live_AbC1MnPq...

Heilo heeft drie authenticatiemodi:

• Bearer (API-sleutels hk_live_…) — voor de publieke API. Geen CSRF, geen cookies.
• Sessiecookies — voor de webapp (heilo.io). NIET gebruiken voor de publieke API.
• HMAC-SHA256 — voor Webhooks die Heilo naar UW endpoint stuurt (u verifieert de signature-header).

Het veld environment in het /me-antwoord heeft vandaag altijd de waarde live. Testsleutels zijn gepland.

Alle publieke endpoints bevinden zich onder /api/v1/. Productie:

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

Elk /api/v1-endpoint vereist Bearer. /me hieronder dient voor introspectie van de sleutel; het lezen van gesprekken staat in de sectie "Calls". Behandel webhooks als de primaire gegevensbron bij het integreren van een CRM — REST is voor introspectie en het lezen van geselecteerde metadata.

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

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

Lees-endpoints voor gesprekken. Vereisen de scope read.calls.

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

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

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

Opnamebestanden worden NIET via de API beschikbaar gesteld — ze worden gewist conform de wettelijke bewaartermijn (AVG). De API geeft gespreksmetadata en transcripttekst terug.

Uurlimieten per sleutel en per gebruiker (som van alle sleutels). Reset op het hele UTC-uur. Elk verzoek telt mee, ongeacht de responsstatus.

Bij overschrijding geven we 429 terug met een Retry-After-header (seconden tot 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

Alle fouten geven een uniforme JSON-vorm terug met error.code (stabiel) en error.message (leesbaar, kan wijzigen). Log de code, niet het bericht.

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

De code SUBSCRIPTION_INACTIVE komt in twee situaties voor: HTTP 402 — het Heilo-abonnement is verlopen (betaling), en HTTP 409 — het webhook-abonnement is gepauzeerd (bijv. bij de actie Test); klik in dat geval eerst op "Opnieuw verifiëren".

Heilo doet na elk event een POST met JSON naar uw endpoint. Abonnementen worden aangemaakt via de kaart "Webhook-abonnementen" — vereist een handshake bij activering. Elk verzoek bevat een HMAC-handtekening die u moet verifiëren:

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 */ }
}

Beleid voor opnieuw proberen en pauzeren:

• Tijdelijke fouten (HTTP 408/429/5xx, netwerk) worden opnieuw geprobeerd met exponential backoff (2min, 5min, 30min, 2u) — daarna dead-letter na 5 pogingen.
• Permanente fouten (HTTP 401/403/422) pauzeren het abonnement onmiddellijk — geen nieuwe pogingen.
• 50 opeenvolgende tijdelijke fouten, of 2 opeenvolgende HTTP 410 Gone (bijv. een verwijderd Make-scenario), pauzeren het abonnement eveneens.
• Hervat een gepauzeerd abonnement met "Opnieuw verifiëren" — een nieuwe handshake reactiveert de wachtrij.

Wordt een abonnement automatisch gepauzeerd, dan sturen we een e-mail naar het adres van de accounteigenaar. Dead-letter-events kunt u opnieuw versturen met de knop "Opnieuw versturen" in het Afleverlog — nadat het abonnement opnieuw is geverifieerd.

Heilo ondersteunt twee activeringsmodellen voor webhook-abonnementen. De standaard (permissief) past bij Zapier / Make / typische CRM-endpoints. Strict komt overeen met het model van de Slack Events API — handig voor eigen servers die de challenge synchroon kunnen terugsturen.

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

U kiest de modus bij het aanmaken van het abonnement (verification_mode in POST /api/v1/webhook-subscriptions, standaard permissive). Het wijzigen van de modus na aanmaak vereist verwijderen + opnieuw aanmaken — bewust, omdat het de contractsemantiek wijzigt.

Limieten: max. 20 actieve abonnementen per account (te overschrijven via env). Een abonnement wordt automatisch gepauzeerd na 50 opeenvolgende tijdelijke fouten of 2 opeenvolgende HTTP 410, en onmiddellijk bij HTTP 401/403/422.

Stripe-compatibel formaat. signed_string = "<unix_ts>.<raw_body>" (gescheiden door een punt). Verifieer altijd de RAW request body (vóór het parsen van JSON) — elke normalisatie wijzigt de handtekening.

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

import { createHmac, timingSafeEqual } from 'crypto';

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

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

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

Standaardtolerantie van 300s (5 min) voorkomt replay-aanvallen. Serverklokken moeten via NTP gesynchroniseerd zijn.

Het ondertekeningsgeheim tonen we maar één keer — bij het aanmaken van het abonnement. Bent u het kwijt of vermoedt u een lek: verwijder het abonnement en maak het opnieuw aan met dezelfde URL (het adres in Zapier/Make verandert niet). Rotatie van het geheim zonder verwijderen is gepland.

Kies event_types bij het aanmaken van een abonnement. Elk event heeft een uniek event_id (UUID v5) en wordt per abonnement ontdubbeld.

De eerste gebeurtenis die u ontvangt is webhook.test — een testbericht met data._test = true. Gebruik het om uw velden te mappen of filter het eruit.

Hieronder het data-object van elk event. Veldnamen, types en enum-waarden maken deel uit van het API-contract en veranderen binnen v1 niet van betekenis; er kunnen in de loop van de tijd nieuwe, optionele velden bijkomen.

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