Documentation Index
Fetch the complete documentation index at: https://docs.lina.doolehealth.com/llms.txt
Use this file to discover all available pages before exploring further.
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.lina.health/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"]
}'
{
"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": [...]
}
}
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');
});
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 |
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.
