Webhooks

Descripción general

Los webhooks permiten que LINA envíe notificaciones HTTP POST a tu servidor cuando ocurren eventos relevantes. Esto elimina la necesidad de hacer polling y te permite reaccionar en tiempo real.

Eventos disponibles

Evento	Descripción
`patient.created`	Se ha registrado un nuevo paciente
`form.completed`	Un paciente ha completado un formulario
`call.ended`	Una llamada IA ha finalizado
`conversation.ended`	Una conversación de chat IA ha finalizado
`credits.low`	Tu saldo de créditos está por debajo del 10% de la asignación mensual
`schedule.sent`	Un formulario programado ha sido enviado al paciente

Configuración

Registrar un webhook

curl -X POST https://api.linahealthcareplatform.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhooks/lina",
    "events": ["form.completed", "call.ended", "credits.low"]
  }'

Respuesta:

{
  "id": "wh_abc123",
  "url": "https://tu-servidor.com/webhooks/lina",
  "events": ["form.completed", "call.ended", "credits.low"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "status": "active",
  "createdAt": "2026-05-14T10:00:00Z"
}

El campo secret solo se muestra una vez en la respuesta de creación. Guárdalo de forma segura — lo necesitarás para verificar las firmas.

Recibir eventos

LINA enviará peticiones POST a tu URL con el siguiente formato:

{
  "id": "evt_xyz789",
  "event": "form.completed",
  "createdAt": "2026-05-14T12:34:56Z",
  "data": {
    "formId": "form_abc123",
    "patientId": "pat_xyz789",
    "responses": [...]
  }
}

Headers incluidos:

Content-Type: application/json
X-Lina-Signature: sha256=a1b2c3d4...
X-Lina-Event: form.completed
X-Lina-Delivery: evt_xyz789

Responder correctamente

Tu endpoint debe responder con un código HTTP 2xx en un máximo de 10 segundos. Cualquier otra respuesta se considera un fallo y se reintentará.

Verificación de firma

Todos los webhooks incluyen una firma HMAC-SHA256 en el header X-Lina-Signature. Siempre debes verificar esta firma para asegurar que la petición proviene de LINA.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// En tu handler Express:
app.post('/webhooks/lina', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-lina-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, process.env.LINA_WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Procesar el evento...
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# En tu handler Flask:
@app.route('/webhooks/lina', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Lina-Signature')
    is_valid = verify_webhook_signature(
        request.data, signature, os.environ['LINA_WEBHOOK_SECRET']
    )

    if not is_valid:
        return 'Invalid signature', 401

    event = request.get_json()
    # Procesar el evento...
    return 'OK', 200

Nunca proceses un webhook sin verificar la firma. Un atacante podría enviar eventos falsos a tu endpoint.

Política de reintentos

Si tu endpoint no responde con 2xx, LINA reintentará el envío con backoff exponencial:

Intento	Retraso
1º reintento	1 minuto
2º reintento	10 minutos
3º reintento	1 hora

Después del tercer intento fallido, el evento se marca como failed y no se reintenta más. Puedes consultar los eventos fallidos en el panel de LINA o vía API.

Si tu endpoint falla en más del 95% de los envíos durante 24 horas, el webhook se desactivará automáticamente. Recibirás un email de notificación y podrás reactivarlo desde el panel.

Buenas prácticas

Responde rápido — Devuelve 200 inmediatamente y procesa el evento de forma asíncrona.
Idempotencia — Usa el id del evento para evitar procesar duplicados.
Verifica siempre — Comprueba la firma HMAC en cada petición.
Usa HTTPS — Solo se admiten URLs con HTTPS en producción.
Registra eventos — Almacena los eventos recibidos para debugging y auditoría.

Comenzar

Guías

Descripción general

Eventos disponibles

Configuración

Verificación de firma

Política de reintentos

Buenas prácticas

​Descripción general

​Eventos disponibles

​Configuración

​Verificación de firma

​Política de reintentos

​Buenas prácticas

Descripción general

Eventos disponibles

Configuración

Verificación de firma

Política de reintentos

Buenas prácticas