Referencia de la API v1

La vía más rápida para conectar un CRM a Heilo. La referencia completa de la API está más abajo.

1. Exponga un endpoint de webhook en su CRM o middleware (sin código: use Zapier/Make; vea la guía más abajo).
2. Añada una suscripción en Heilo (Ajustes → Integraciones) para call.completed (opcionalmente también call.outbound.attempted).
3. Reciba call.completed y verifique la firma (cabecera Heilo-Signature, HMAC; vea más abajo).
4. Deduplique por event_id (cabecera heilo-event-id); data.call_id agrupa los eventos de la misma llamada.
5. Mapee los campos a su CRM: busque/cree un contacto por teléfono, cree un lead/negocio y adjunte una actividad/nota (resumen + enlace de la grabación).

¿Sin código? La guía de conexión sin código (Zapier/Make) lo explica paso a paso.

La API pública usa tokens Bearer. Genere una clave API desde la tarjeta «Claves API» de la página de Integraciones y envíela en la cabecera:

Authorization: Bearer hk_live_AbC1MnPq...

Heilo tiene tres modos de autenticación:

• Bearer (claves API hk_live_…): para la API pública. Sin CSRF, sin cookies.
• Cookies de sesión: para la aplicación web (heilo.io). NO las use para la API pública.
• HMAC-SHA256: para los Webhooks que Heilo envía a SU endpoint (usted verifica la cabecera de firma).

El campo environment en la respuesta de /me tiene hoy siempre el valor live. Las claves de prueba están previstas.

Todos los endpoints públicos están bajo /api/v1/. Producción:

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

Cada endpoint de /api/v1 requiere Bearer. El /me siguiente sirve para la introspección de la clave; la lectura de llamadas está en la sección «Llamadas». Al integrar un CRM, trate los webhooks como la fuente de datos principal: REST sirve para la introspección y para leer metadatos seleccionados.

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

Endpoints de lectura para llamadas. Requieren el 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..."

Los archivos de grabación NO se exponen a través de la API: se borran según la retención legal (RGPD). La API devuelve los metadatos de la llamada y el texto de la transcripción.

Límites por hora por clave y por usuario (suma de todas las claves). Se reinician en la hora UTC. Cada solicitud cuenta, independientemente del estado de la respuesta.

Cuando se supera, devolvemos 429 con la cabecera Retry-After (segundos hasta el reinicio):

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

Todos los errores devuelven una estructura JSON uniforme con error.code (estable) y error.message (legible por humanos, puede cambiar). Registre el code, no el message.

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

El código SUBSCRIPTION_INACTIVE aparece en dos situaciones: HTTP 402, la suscripción de Heilo ha caducado (pago), y HTTP 409, la suscripción del webhook está pausada (p. ej., con la acción de prueba); en ese caso, haga clic primero en «Volver a verificar».

Heilo envía un POST con JSON a su endpoint tras cada evento. Las suscripciones se crean desde la tarjeta «Suscripciones de Webhook»: requiere un handshake en la activación. Cada solicitud incluye una firma HMAC que debe verificar:

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

Política de reintentos y pausa:

• Los errores transitorios (HTTP 408/429/5xx, red) se reintentan con backoff exponencial (2 min, 5 min, 30 min, 2 h) y luego pasan a dead-letter tras 5 intentos.
• Los errores permanentes (HTTP 401/403/422) pausan la suscripción de inmediato, sin reintentos.
• 50 fallos transitorios consecutivos, o 2 HTTP 410 Gone consecutivos (p. ej. un escenario de Make eliminado), también pausan la suscripción.
• Reanude una suscripción pausada con «Volver a verificar»: un nuevo handshake reactiva la cola.

Si una suscripción se pausa automáticamente, enviamos un correo a la dirección del propietario de la cuenta. Puede reenviar los eventos en dead-letter con el botón «Reenviar» del Registro de entregas, una vez que la suscripción supere la nueva verificación.

Heilo admite dos modelos de activación para las suscripciones de webhook. El predeterminado (permisivo) encaja con Zapier / Make / los endpoints típicos de CRM. El estricto coincide con el modelo de la Slack Events API: útil para servidores personalizados que pueden devolver el challenge de forma síncrona.

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

Usted elige el modo al crear la suscripción (verification_mode en POST /api/v1/webhook-subscriptions, permisivo por defecto). Cambiar el modo tras la creación requiere eliminar y volver a crear: es intencionado, ya que cambia la semántica del contrato.

Límites: máximo 20 suscripciones activas por cuenta (configurable por variable de entorno). Una suscripción se pausa automáticamente tras 50 fallos transitorios consecutivos o 2 HTTP 410 consecutivos, e inmediatamente con HTTP 401/403/422.

Formato compatible con Stripe. signed_string = "<unix_ts>.<raw_body>" (separados por un punto). Verifique siempre el cuerpo RAW de la solicitud (antes de analizar el JSON): cualquier normalización cambia la firma.

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

La tolerancia predeterminada de 300 s (5 min) evita los ataques de repetición. Los relojes del servidor deben estar sincronizados por NTP.

El secreto de firma se muestra solo una vez, al crear la suscripción. Si lo pierde o sospecha una filtración: elimine la suscripción y créela de nuevo con la misma URL (la dirección en Zapier/Make no cambia). La rotación del secreto sin eliminar está prevista.

Elija los event_types al crear una suscripción. Cada evento tiene un event_id único (UUID v5) y se deduplica por suscripción.

El primer evento que recibirá es webhook.test, un mensaje de prueba con data._test = true. Úselo para mapear los campos o fíltrelo.

A continuación, el objeto data de cada evento. Los nombres de campo, tipos y valores enumerados forman parte del contrato de la API y no cambian de significado dentro de v1; con el tiempo pueden añadirse nuevos campos opcionales.

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