API Reference v1

The fastest path to connect a CRM to Heilo. The full API reference is below.

1. Expose a webhook endpoint in your CRM or middleware (no code: use Zapier/Make — see the guide below).
2. Add a subscription in Heilo (Settings → Integrations) for call.completed (optionally also call.outbound.attempted).
3. Receive call.completed and verify the signature (Heilo-Signature header, HMAC — see below).
4. Deduplicate by event_id (heilo-event-id header); data.call_id groups events of the same call.
5. Map the fields to your CRM: find/create a contact by phone, create a lead/deal, and attach an activity/note (summary + recording link).

No code? The no-code connection guide (Zapier/Make) walks through it step by step.

Public API uses Bearer tokens. Generate an API key from the "API keys" card on the Integrations page and send it in the header:

Authorization: Bearer hk_live_AbC1MnPq...

Heilo has three auth modes:

• Bearer (API keys hk_live_…) — for Public API. No CSRF, no cookies.
• Session cookies — for the web app (heilo.io). Do NOT use for Public API.
• HMAC-SHA256 — for Webhooks Heilo sends to YOUR endpoint (you verify signature header).

The environment field in the /me response is always live today. Test keys are planned.

All public endpoints live under /api/v1/. Production:

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

Every /api/v1 endpoint requires Bearer. /me below is for key introspection; reading calls is in the "Calls" section. When integrating a CRM, treat webhooks as the primary data source — REST is for introspection and reading selected 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" }
}

Read endpoints for calls. Require the read.calls scope.

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

Recording files are NOT exposed via the API — they are erased per legal retention (GDPR). The API returns call metadata and transcript text.

Hourly limits per-key and per-user (sum of all keys). Reset on the UTC hour. Every request counts, regardless of response status.

When exceeded we return 429 with Retry-After header (seconds until 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

All errors return a uniform JSON shape with error.code (stable) and error.message (human-readable, may change). Log the code, not the message.

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

The SUBSCRIPTION_INACTIVE code appears in two situations: HTTP 402 — your Heilo subscription has lapsed (billing), and HTTP 409 — the webhook subscription is paused (e.g. on the Test action); in that case click "Reverify" first.

Heilo POSTs JSON to your endpoint after each event. Subscriptions are created from the "Webhook subscriptions" card — requires a handshake on activation. Every request includes an HMAC signature you must verify:

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

Retry and pause policy:

• Transient errors (HTTP 408/429/5xx, network) retry with exponential backoff (2min, 5min, 30min, 2h) — then dead-letter after 5 attempts.
• Permanent errors (HTTP 401/403/422) pause the subscription immediately — no retries.
• 50 consecutive transient failures, or 2 consecutive HTTP 410 Gone (e.g. deleted Make scenario), also pause the subscription.
• Resume a paused subscription with "Reverify" — a fresh handshake reactivates the queue.

When a subscription is paused automatically, we send an e-mail to the account owner. You can resend dead-lettered events with the "Resend" button in the Delivery log — once the subscription passes reverification.

Heilo supports two activation models for webhook subscriptions. The default (permissive) fits Zapier / Make / typical CRM endpoints. Strict matches the Slack Events API model — useful for custom servers that can synchronously echo the challenge.

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

You pick the mode at subscription creation (verification_mode in POST /api/v1/webhook-subscriptions, default permissive). Changing mode post-creation requires delete + recreate — intentional, as it changes the contract semantics.

Limits: max 20 active subscriptions per account (env-overridable). A subscription is auto-paused after 50 consecutive transient failures or 2 consecutive HTTP 410, and immediately on HTTP 401/403/422.

Stripe-compatible format. signed_string = "<unix_ts>.<raw_body>" (dot-separated). Always verify the RAW request body (before JSON parsing) — any normalization changes the signature.

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);
}

Default 300s (5 min) tolerance prevents replay attacks. Server clocks must be NTP-synced.

The signing secret is shown only once — when the subscription is created. If you lose it or suspect a leak: delete the subscription and create it again with the same URL (the address in Zapier/Make stays the same). In-place secret rotation is planned.

Pick event_types when creating a subscription. Each event has a unique event_id (UUID v5) and deduplicates per subscription.

The first event you receive is webhook.test — a test message with data._test = true. Use it to map your fields or filter it out.

Below is the data object of every event. Field names, types and enum values are part of the API contract and do not change meaning within v1; new optional fields may be added over time.

{
  "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": "..."
  }
}