--- seo_title: Webhooks y Notificaciones de Trabajos de Conversión | EnConvert meta_desc: Recibe un POST de webhook vía callback_url al finalizar trabajos asíncronos. También admite notificaciones por correo y sondeo con GET /v1/convert/batch/{batch_id}. keywords: api de callbacks webhook para conversión, webhook al completar trabajo asíncrono, webhook cuando termina la conversión de archivos, parámetro callback_url, api de sondeo de estado de lote, notificación por correo al completar conversión, ejemplo de payload json de webhook, probar api de callback webhook --- # Callbacks de Webhook y Notificaciones de Trabajos de Conversión EnConvert te avisa cuando los trabajos de conversión asíncronos y por lotes finalizan a través de tres mecanismos independientes: sondeo de `GET /v1/convert/batch/{batch_id}`, callbacks de webhook mediante el parámetro `callback_url`, y notificaciones por correo mediante `notification_email`. Los tres se pueden combinar en una misma solicitud, y los archivos terminados se recuperan mediante las URL de descarga incluidas en la respuesta de estado del lote. Esta página documenta los payloads de callback, los requisitos de entrega y las restricciones por plan de cada método.
Solo claves privadas: Las notificaciones de trabajos y el sondeo del estado del lote solo están disponibles al autenticarse con una clave de API privada (X-API-Key: sk_...). Las claves públicas no admiten procesamiento asíncrono ni por lotes.
--- ## Resumen | Método | Parámetro / Endpoint | Descripción | |--------|---------------------|-------------| | Polling | `GET /v1/convert/batch/{batch_id}` | Sondea el estado en tiempo real, los recuentos de progreso y las URL de descarga. | | Email | `notification_email` | Envía un correo de finalización con el estado del trabajo y un enlace al panel. | | Webhook | `callback_url` | Envía una solicitud POST con los resultados del trabajo a tu servidor. | Los tres métodos funcionan tanto para trabajos asíncronos de una sola URL como para trabajos por lotes de múltiples URL en los endpoints [url-to-pdf](/es/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/es/docs/endpoints/convert/web-pages/url-to-screenshot.md), [website-to-pdf](/es/docs/endpoints/convert/web-pages/website-to-pdf.md) y [website-to-screenshot](/es/docs/endpoints/convert/web-pages/website-to-screenshot.md). --- ## Sondeo del estado del lote La forma recomendada de hacer seguimiento del progreso de un trabajo. Sondea el endpoint de estado del lote con el `batch_id` devuelto en la respuesta inicial 202. ``` GET /v1/convert/batch/{batch_id} X-API-Key: sk_your_private_key ``` ### Respuesta ```json { "batch_id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing", "total": 3, "completed": 1, "failed": 0, "in_progress": 2, "output_mode": "individual", "zip_download_url": null, "items": [ { "source_url": "https://example.com/page-1", "status": "Success", "download_url": "https://spaces.example.com/...", "output_file_size": 184320, "duration": "3.12" }, { "source_url": "https://example.com/page-2", "status": "In Progress", "download_url": null, "output_file_size": null, "duration": null } ] } ``` ### Valores de estado | Estado | Significado | |--------|---------| | `processing` | Al menos una URL todavía se está convirtiendo. | | `completed` | Todas las URL se convirtieron correctamente. | | `partial` | Todas las URL terminaron, pero algunas fallaron. | | `failed` | Todas las URL fallaron. | En modo ZIP (`output_mode: "zip"`), se proporciona un `zip_download_url` para el archivo completo cuando finaliza. En modo individual, cada elemento tiene su propio `download_url`. Para conocer todos los detalles del esquema de respuesta, consulta [Procesamiento por lotes](/es/docs/guides/batch-processing.md#batch-status-polling). --- ## Notificaciones por correo electrónico Incluye el parámetro `notification_email` en tu solicitud para recibir un correo cuando el trabajo finalice. Si omites este parámetro, el correo se envía de forma predeterminada a la **dirección de correo del propietario del proyecto**. ### Ejemplo ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async_mode": true, "notification_email": "team@yourcompany.com" }' ``` ### Respuesta (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Contenido del correo El correo de finalización incluye: - **Encabezado de estado** con un banner de color (verde para éxito, rojo para fallo) - **Job ID** y **Batch ID** (si forma parte de un lote) - **Texto de estado** (éxito o fallo) - **Texto fijo** que indica a los usuarios que descarguen los archivos desde su panel - **Tabla de tareas** (solo trabajos por lotes en modo ZIP) con las columnas: #, URL (truncada a 50 caracteres), estado y nombre del archivo de salida En modo individual (incluidos los lotes individuales de múltiples URL), cada correo por URL contiene únicamente el job ID y el estado -- sin tabla de tareas. En modo ZIP, el único correo del lote incluye la tabla de tareas completa con todas las URL y sus estados.
Comportamiento predeterminado: Si no incluyes notification_email en tu solicitud, el correo de finalización se envía automáticamente a la dirección de correo del propietario del proyecto. Para suprimir por completo las notificaciones por correo, este valor predeterminado no se puede deshabilitar actualmente.
--- ## Callbacks por webhook Incluye el parámetro `callback_url` en tu solicitud para recibir un POST de webhook cuando el trabajo finalice. Requiere un plan con acceso a webhooks. ### Ejemplo ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async_mode": true, "callback_url": "https://yourapp.com/webhooks/enconvert" }' ``` ### Respuesta (HTTP 202 Accepted) ```json { "status": "processing", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "url_count": 1, "output_format": "individual" } ``` ### Payload del callback en modo de URL única / individual En modo individual, se **envía un POST separado por cada URL** a medida que finaliza: ```json { "job_id": "12345", "status": "success", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_uri": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf", "filename": "example_20260405_123456789.pdf", "file_size": 184320 } ``` Para una conversión fallida: ```json { "job_id": "12345", "status": "failed", "batch_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Payload del callback en modo ZIP En modo ZIP, se **envía un único POST cuando el lote completo finaliza**: ```json { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "success", "batch_id": "550e8400-e29b-41d4-a716-446655440000", "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip", "filename": "batch_20260405_123456789.zip", "file_size": 456789, "total_tasks": 3, "successful_tasks": 2, "failed_tasks": 1, "tasks": [ {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"}, {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"}, {"url": "https://invalid-url.example", "status": "failed", "error": "Page load timeout"} ] } ```
Comportamiento de notificación individual vs ZIP: En modo individual, recibes N POST de webhook separados (uno por URL) y N correos separados. En modo ZIP, recibes un POST de webhook y un correo para todo el lote. Diseña tu manejador de webhooks en consecuencia.
--- ## Uso conjunto de varios métodos de notificación Puedes combinar polling, email y webhook en la misma solicitud. Los tres funcionan de forma independiente. ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": [ "https://example.com/page-1", "https://example.com/page-2" ], "notification_email": "team@yourcompany.com", "callback_url": "https://yourapp.com/webhooks/enconvert" }' ``` Tras enviar la solicitud, puedes: 1. **Sondear** `GET /v1/convert/batch/{batch_id}` para conocer el progreso en tiempo real 2. **Recibir un POST de webhook** en tu URL de callback cuando cada conversión termine 3. **Recibir un correo** en la dirección especificada cuando cada conversión termine --- ## Parámetros de notificación | Parámetro | Tipo | Obligatorio | Predeterminado | Descripción | Restricción por plan | |-----------|------|----------|---------|-------------|-------------| | `notification_email` | `string` | No | Correo del propietario del proyecto | Dirección de correo que recibe las notificaciones de finalización del trabajo. | -- | | `callback_url` | `string` | No | -- | URL que recibe un POST de webhook al finalizar. | Requiere acceso a webhooks | --- ## Requisitos de entrega de webhooks | Requisito | Detalle | |-------------|--------| | **Método** | EnConvert envía una solicitud `POST` con `Content-Type: application/json`. | | **Tiempo de espera** | Tu endpoint debe responder en **30 segundos**. | | **Códigos de éxito** | Los HTTP `200`, `201`, `202` o `204` se consideran entrega exitosa. | | **Reintentos** | No hay reintentos en caso de fallo. Si la entrega del webhook falla (respuesta sin éxito o tiempo de espera agotado), los resultados siguen disponibles mediante el sondeo del estado del lote. | | **Autenticación** | No se envían encabezados de autenticación. Valida el `batch_id` con tus registros si es necesario. | --- ## Restricciones por plan de suscripción | Función | Founding | Indie | Studio | Enterprise | |---------|------|---------|-----|------------| | Modo asíncrono | No | Sí | Sí | Sí | | Sondeo del estado del lote | No | Sí | Sí | Sí | | Notificaciones por correo | No | Sí | Sí | Sí | | Callbacks por webhook (`callback_url`) | No | No | Sí | Sí |
Nota: Las notificaciones por correo no tienen una restricción de función independiente -- están disponibles para cualquier usuario de clave de API privada con acceso asíncrono. El parámetro notification_email no requiere una función de plan específica. Los callbacks por webhook (callback_url) requieren la función has_webhook, que está disponible en los planes Studio y superiores.
--- ## Pruebas de webhooks Durante el desarrollo, usa [webhook.site](https://webhook.site) para generar una URL de callback temporal con fines de prueba: ```bash curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "async_mode": true, "callback_url": "https://webhook.site/your-unique-id" }' ``` Visita tu panel de webhook.site para inspeccionar el payload exacto del callback una vez que el trabajo finalice. ## Preguntas frecuentes ### ¿Cómo recibo un callback de webhook cuando finaliza un trabajo de conversión de archivos? Incluye el parámetro `callback_url` en tu solicitud con una clave de API privada. EnConvert envía un `POST` con `Content-Type: application/json` a esa URL cuando el trabajo finaliza. Los callbacks de webhook requieren un plan con acceso a webhooks (Studio, Production o Enterprise). ### ¿EnConvert reintenta las entregas de webhook fallidas? No. Tu endpoint debe responder en 30 segundos con HTTP `200`, `201`, `202` o `204`. Si la entrega falla, los resultados siguen disponibles mediante el sondeo del estado del lote en `GET /v1/convert/batch/{batch_id}`. ### ¿Puedo usar notificaciones por correo, webhook y polling juntos? Sí. `notification_email`, `callback_url` y el sondeo de estado funcionan de forma independiente y se pueden combinar en la misma solicitud. Si se omite `notification_email`, el correo de finalización se envía por defecto a la dirección del propietario del proyecto. ### ¿Por qué recibo un webhook por cada URL en lugar de uno para todo el lote? En modo individual recibes N POST de webhook separados (uno por URL) y N correos separados. Para recibir un único webhook y un único correo para todo el lote, usa el modo ZIP, que envía un solo POST con `total_tasks`, `successful_tasks`, `failed_tasks` y un array `tasks`. ### ¿Cómo puedo probar los callbacks de webhook durante el desarrollo? Usa webhook.site para generar una URL temporal y pásala como `callback_url` en tu solicitud. El panel de webhook.site muestra el payload JSON exacto que EnConvert entrega cuando el trabajo finaliza.