Webhooks
Notificaciones en Tiempo Real
Recibe notificaciones HTTP cuando ocurren eventos importantes en tus traducciones.
Eventos Disponibles
book.completed
Se dispara cuando un libro termina de traducirse y el EPUB/PDF está listo
{
"event": "book.completed",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"bookId": "clx123...",
"title": "Mi Libro",
"status": "completed",
"downloadUrl": "/api/download/clx123"
}
}translation.error
Se dispara cuando ocurre un error durante la traducción
{
"event": "translation.error",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"bookId": "clx123...",
"title": "Mi Libro",
"error": "Rate limit exceeded",
"chapterIndex": 5
}
}Configuración
Crear un Webhook
Configura un endpoint para recibir notificaciones
1. Via API:
POST /api/webhooks
Authorization: Bearer lector_xxx
Content-Type: application/json
{
"url": "https://tu-servidor.com/webhook",
"events": ["book.completed", "translation.error"]
}2. Via Dashboard: Ve a Configuración → Webhooks → Crear nuevo
Verificación de Firma
Verifica que las peticiones vienen de LectorAI
Cada webhook incluye un header X-Webhook-Signature con una firma HMAC-SHA256 del payload usando tu secret.
import crypto from 'crypto';
function verifyWebhook(payload: string, signature: string, secret: string) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// En tu endpoint
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhook(
JSON.stringify(req.body),
signature,
process.env.WEBHOOK_SECRET
);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// Procesar webhook...
res.status(200).send('OK');
});Política de Reintentos
Si tu endpoint no responde con un código 2xx, reintentamos automáticamente:
- 1er reintentoDespués de 1 minuto
- 2do reintentoDespués de 5 minutos
- 3er reintentoDespués de 30 minutos
Después de 3 intentos fallidos, el webhook se marca como fallido y puedes verlo en el historial de entregas.
Ejemplo con SDK
import { LectorAI } from '@lectorai/sdk';
const client = new LectorAI({ apiKey: 'lector_xxx' });
// Crear webhook
const webhook = await client.webhooks.create({
url: 'https://tu-servidor.com/webhook',
events: ['book.completed', 'translation.error']
});
console.log('Webhook creado:', webhook.id);
console.log('Secret:', webhook.secret); // Guarda este secret!
// Listar webhooks
const webhooks = await client.webhooks.list();
// Eliminar webhook
await client.webhooks.delete(webhook.id);
// Test webhook (envía evento de prueba)
await client.webhooks.test(webhook.id);Configura tu primer Webhook
Empieza a recibir notificaciones en tiempo real