Webhooks y entrega

Después de cada llamada, Hanc.AI puede enviar la llamada —resumen, transcripción, campos extraídos— a su propio sistema: un sistema de tickets, un CRM, un ERP o cualquier endpoint HTTPS. Esta página describe exactamente cómo se comporta esa entrega: qué ocurre cuando su servidor está caído, con qué frecuencia reintentamos, qué debe permitir su firewall y qué aspecto tiene la petición.

Todos los planes

La entrega posterior a la llamada, con reintentos y registro de entregas, está disponible en todos los planes, incluido el Free.

Qué se envía y cuándo

La petición sale cuando la llamada ha terminado y su análisis ha concluido (resumen, sentimiento, sus campos extraídos), normalmente unos segundos después de colgar.

Origen	Dónde se configura
Acción «Llamada API»	Agente → Acciones → Post call → Llamada API
Paso de workflow	Editor de workflows → paso de herramienta Llamada API con Cuándo se ejecuta: Después de la llamada
Webhook del agente	El campo webhook_url del agente (referencia de la API)

Las peticiones que un agente realiza durante una conversación (herramientas en vivo) no se tratan aquí: se necesitan en ese mismo instante y nunca se repiten más tarde.

Cuando su servidor no está disponible

No se pierde nada. La petición se guarda en una cola de entrega antes del primer intento y permanece en ella hasta que su servidor la acepta o se agota la programación.

• Una entrega se considera correcta cuando su endpoint responde con cualquier estado 2xx en un plazo de 30 segundos.
• Todo lo demás se reintenta: conexión rechazada, errores de DNS o TLS, tiempo de espera agotado y cualquier otro estado (5xx, 429 y también 4xx). Si una clave de API ha caducado y usted la renueva, las llamadas pendientes llegan por sí solas.
• Cada intento envía la misma petición con el mismo ID de entrega.

Programación de reintentos

Intento	Pausa previa	Tiempo desde el fin de la llamada
1	— (de inmediato)	~0
2	1 minuto	~1 min
3	5 minutos	~6 min
4	30 minutos	~36 min
5	2 horas	~2 h 36 min
6	6 horas	~8 h 36 min
7	24 horas	~1 día 8 h
8	48 horas	~3 días 8 h

Son 8 intentos a lo largo de unos 3,4 días, suficiente para cubrir una caída de fin de semana.

Su propia programación

En una acción Llamada API (y en un paso de workflow Llamada API que se ejecuta después de la llamada) puede sustituir la programación en Reintentos en caso de error:

• hasta 10 reintentos,
• cada pausa de 1 minuto a 7 días,
• elimine todas las filas para enviar una sola vez, sin reintentos.

Una acción que usted nunca ha modificado sigue la programación predeterminada indicada arriba.

Tras el último intento

La entrega se marca como No entregado, usted recibe una notificación por correo electrónico, salvo que la haya desactivado, y la petición se conserva durante 30 días. Durante ese tiempo puede enviarla de nuevo con un clic en el registro de entregas o con una llamada a la API. También es posible volver a enviar una entrega que ya se completó correctamente, por ejemplo tras una restauración en su lado.

Con independencia de cualquier webhook, la llamada en sí permanece en su cuenta de Hanc.AI: la transcripción, el resumen, la grabación y los campos extraídos están disponibles en Llamadas y a través de la API. Una caída prolongada retrasa el traspaso a su sistema; no borra la conversación.

Al menos una vez

La entrega es al menos una vez. En casos poco frecuentes —por ejemplo, cuando su servidor procesó una petición pero la respuesta no nos llegó a tiempo— la misma llamada llega dos veces. Utilice X-Hanc-Delivery-Id para reconocer y omitir una repetición.

Notificaciones de fallos

No hace falta que vigile el registro: una acción puede avisarle por correo electrónico cuando su petición no se entrega. Elija en Notificación de fallos, dentro de la acción (o en el paso de workflow):

Ajuste	Cuándo se envía el correo
Tras el último intento (predeterminado)	Una vez, cuando se agota la programación de reintentos y la petición se marca como No entregado
Tras cada intento fallido	Después de cada intento fallido, con la hora del siguiente, y también después del último
No notificar	Nunca; los fallos solo se ven en el registro

El correo indica la acción y el agente, el host de su servidor, qué respondió (por ejemplo HTTP 503 o timeout after 30s) y qué intento fue de cuántos, y enlaza al registro de entregas. El último indica además hasta cuándo se conserva la petición y que puede enviarse de nuevo.

Enviar a define el destinatario, normalmente quien opera el sistema receptor. Si se deja vacío, el correo se envía al titular de la cuenta. Se redacta en el idioma de la cuenta.

Para que una caída no inunde su bandeja de entrada, las notificaciones están limitadas por acción a 10 por hora y 30 por día; la última antes de una pausa indica hasta cuándo dura esta. Todos los fallos siguen quedando anotados en el registro. No se envía notificación sobre una petición que usted reenvía manualmente.

Registro de entregas

Se registra cada intento: hora, estado HTTP o error de red, duración y el comienzo de la respuesta de su servidor.

En la aplicación: CRM → Comunicaciones → abra una entrada de tipo Llamada API. Verá el estado (Entregado, Reintentando, No entregado), todos los intentos, la hora del siguiente y el botón Enviar de nuevo.

A través de la API (autentíquese con su clave de API en x-api-key):

Petición	Resultado
GET /v1/webhook-deliveries	Sus entregas, las más recientes primero. Filtros: status (pending, delivered, failed), agent_id, call_id, limit, offset
GET /v1/webhook-deliveries/{id}	Una entrega con todos sus intentos y el cuerpo de la petición
POST /v1/webhook-deliveries/{id}/resend	La envía de nuevo ahora y devuelve el resultado

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Create ticket",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

Los valores de las cabeceras de la petición almacenada (sus claves) nunca se devuelven.

Red y firewall

Hanc.AI llama a su endpoint: la conexión se abre siempre desde nuestro lado hacia el suyo.

Sentido	Saliente desde Hanc.AI → entrante en su lado
Direcciones IP de origen	178.104.10.47 (servicio de entrega) y 128.140.65.92 (servicio de llamadas, utilizado como alternativa)
Protocolo	HTTPS (TLS 1.2 o posterior). HTTP sin cifrar funciona, pero no se recomienda
Puerto	443, o el puerto que indique su URL
Versión de IP	IPv4
Certificado	Debe ser válido y estar emitido por una autoridad pública; los certificados autofirmados se rechazan
Tiempo de respuesta	Responda en un plazo de 30 segundos; lo ideal es confirmar la recepción de inmediato y procesar en segundo plano
Redirecciones	Se siguen, hasta 5

Lista de permitidos: si su firewall o WAF filtra por dirección de origen, permita las dos direcciones anteriores para la ruta de su webhook. Anunciamos con antelación cualquier cambio de estas direcciones.

No es posible: direcciones dentro de una red privada (10.x, 172.16–31.x, 192.168.x, localhost). El endpoint debe ser accesible desde internet, directamente o a través de su proxy inverso o API gateway.

Navegador: los webhooks funcionan de servidor a servidor. No intervienen ajustes del navegador, extensiones ni puertos abiertos en los puestos de trabajo de los empleados.

Formato de la petición

POST, PUT y PATCH llevan un cuerpo JSON (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Customer reports a broken router and asks for a callback…",
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Campo	Contenido
call_summary	Resumen de la conversación
transcription	Conversación completa, turno a turno, con marcas de tiempo
call_from, call_to, direction	Llamante, número llamado, entrante o saliente
start_timestamp, end_timestamp, duration	Tiempo Unix y duración en milisegundos
custom_analysis_data	Sus propios campos, extraídos de la conversación; véase Variables de recuperación
collected_data	Datos que el agente recopiló durante la llamada
sentiment, task_achieved	Sentimiento de la conversación y si se alcanzó su objetivo
recording_url	Enlace a la grabación, si la grabación está activada
transfer_history	Transferencias que tuvieron lugar durante la llamada

Para GET y DELETE, los mismos campos viajan en la query string; los valores anidados, como transcription, se omiten.

Cabeceras

Cabecera	Significado
X-Hanc-Delivery-Id	Identifica la entrega. Idéntica en todos los intentos: utilícela para omitir duplicados
X-Hanc-Attempt	Número del intento, empezando por 1
X-Correlation-Id	Identificador interno de trazabilidad; indíquelo cuando contacte con el soporte
User-Agent	HANC-Webhooks/1.0
sus cabeceras	Todo lo que haya configurado en la acción

Autenticación

Usted decide cómo nos reconoce su endpoint:

• Clave de API o token: añada una cabecera a la acción, p. ej. Authorization: Bearer <token> o X-API-Key: <key>. Las cabeceras se envían en cada intento.
• Autenticación básica: Authorization: Basic <base64(user:password)>.
• Parámetro de consulta: para sistemas que esperan la clave en la URL.
• Dirección de origen: permita únicamente las direcciones IP indicadas arriba.

Los métodos pueden combinarse; lo habitual es una clave más una lista de IP permitidas.

Adaptar la petición a su sistema

De forma predeterminada, la petición lleva la llamada completa (véase Formato de la petición). Para un sistema que espera su propia estructura —como la mayoría de los sistemas de tickets—, usted mismo describe esa estructura y la rellena a partir de la llamada.

Variables

En una acción Llamada API posterior a la llamada y en un paso de workflow Llamada API, la URL, las cabeceras, los parámetros de consulta y el cuerpo admiten variables entre llaves dobles. Se rellenan con los datos de la llamada justo antes de que salga la petición.

Variable	Valor
{{call_id}}	ID de la llamada
{{call_from}}, {{call_to}}	Llamante y número llamado
{{customer_phone}}, {{customer_email}}	Número y correo electrónico de la otra parte, sea cual sea el sentido de la llamada
{{call_direction}}, {{call_type}}	inbound / outbound, phone / web
{{call_start}}, {{call_end}}	Inicio y fin, ISO 8601 (UTC)
{{call_duration}}	Duración en segundos
{{call_summary}}	Resumen de la conversación
{{call_transcription}}	Conversación completa como texto
{{call_sentiment}}, {{call_task_achieved}}	Sentimiento y si se alcanzó el objetivo
{{call_recording_url}}	Enlace a la grabación
{{agent_id}}	ID del agente
sus campos	Cada Variable de recuperación por su nombre, p. ej. {{customer_number}}, {{priority}}, y cada variable que un workflow haya recopilado durante la llamada

Reglas que conviene conocer:

• Un campo del cuerpo que consta de una sola variable conserva el tipo de esa variable: "priority": "{{priority}}" se envía como el número 3, y "urgent": "{{urgent}}" como true. Si hay texto alrededor de una variable, el valor pasa a ser texto.
• Un valor colocado en la URL se codifica automáticamente con codificación porcentual (+43… pasa a ser %2B43…).
• Una variable para la que la llamada no tiene valor se envía vacía, nunca como el literal {{name}}.

En la aplicación, el botón {x} de un campo muestra la lista de variables disponibles; en el cuerpo, al escribir {{ se sugieren.

Cuerpo

En Cuerpo (JSON), dentro de la acción, usted escribe el objeto JSON que espera su sistema, con tantos niveles de anidamiento como haga falta:

{
  "ticket": {
    "subject": "Call from {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Solo sus campos

Con Enviar solo mis campos activado, la petición lleva únicamente su cuerpo y sus parámetros de consulta; los datos de la llamada no se añaden. Si lo deja desactivado, sus campos se envían junto con la llamada completa.

Envío selectivo

Una condición en lenguaje natural («solo si el llamante informa de una avería») decide qué llamadas activan la petición. Varias acciones pueden apuntar a sistemas o endpoints distintos.

Conectar un sistema de tickets

Cualquier sistema de tickets con una API HTTP o un webhook entrante puede recibir llamadas directamente, sin ningún software intermedio. Lo que se necesita en su lado:

1. Un endpoint accesible desde internet por HTTPS que acepte JSON.
2. Una credencial para él (clave de API, token o autenticación básica), introducida como cabecera en la acción.
3. Si filtra por dirección, las dos direcciones IP anteriores en su lista de permitidos.

Después, en la acción:

1. Defina sus campos. Añada Variables de recuperación como número de cliente, categoría del ticket, prioridad, solicita que le devuelvan la llamada. El agente las rellena a partir de la conversación.
2. Escriba el cuerpo con la estructura de la API de su sistema de tickets y coloque las variables donde corresponda.
3. Active Enviar solo mis campos.
4. Pulse Probar configuración API y, a continuación, haga una llamada de prueba.

Con mucho gusto preparamos el cuerpo para su sistema junto con usted.

Pruebas

Prueba de conexión. El botón Probar configuración API de la acción envía de inmediato una petición de ejemplo y muestra si se alcanzó su endpoint.

Prueba de reintentos, para ver el mecanismo con sus propios ojos:

1. En la acción, defina una programación corta en Reintentos en caso de error, por ejemplo tres pausas de 1 minuto.
2. Detenga su endpoint o bloquee nuestras direcciones en el firewall.
3. Haga una llamada de prueba al agente.
4. Abra CRM → Comunicaciones: la entrada muestra Reintentando, el intento fallido con su error y la hora del siguiente.
5. Vuelva a iniciar el endpoint (o retire el bloqueo). El siguiente intento entrega la llamada y la entrada pasa a Entregado; también puede pulsar Enviar de nuevo para entregar de inmediato.

Lista de comprobación para su endpoint

• Responda 2xx en cuanto la petición esté almacenada; haga el trabajo pesado después.
• Trate X-Hanc-Delivery-Id como clave de idempotencia.
• Responda 4xx/5xx cuando no haya podido aceptar la petición: volveremos a intentarlo.
• Mantenga el certificado válido y las dos direcciones de origen permitidas.