Conciliar webhooks y API en flujos de archivos: recuperar estados sin duplicar acciones

El problema real: el webhook no basta para conocer el estado final

En una integración de archivos, el webhook es una señal, no una fotografía completa del negocio. Puede avisar de que algo ocurrió en Apification Cloud, pero el consumidor puede estar caído, responder tarde, procesar dos veces un reintento o recibir eventos en un orden distinto al esperado. Por eso, conciliar webhooks y API no consiste en desconfiar del webhook, sino en usarlo como disparador y evidencia técnica mientras la API confirma el estado actual del recurso.

El caso típico aparece cuando un archivo se sube a Cloud, se solicita una transformación y después se comparte el resultado. Apification Cloud mantiene archivos, carpetas, servicios editables y resultados generados dentro del mismo workspace, y el File Transformer permite generar resultados sin modificar los originales. Si tu backend pierde conectividad entre la transformación y el compartido, el siguiente paso no debe ser repetir todo: debe reconstruir qué existe, qué terminó y qué acción interna ya se aplicó.

• Trata cada webhook como una notificación de cambio, no como la única fuente de verdad.
• Consulta la API cuando necesites confirmar el estado final de Cloud o de un job.
• Separa el estado técnico de entrega del estado de negocio de tu integración.

Tres capas que no deben mezclarse

La primera capa es la entrega del webhook. Apification permite trabajar con webhooks firmados, reintentos, historial y estadísticas. El historial de entregas puede mostrar la URL destino, la hora del intento, el estado de respuesta y el cuerpo de respuesta. Esa información sirve para diagnosticar si tu endpoint recibió el evento, si respondió error o si aceptó el payload, pero no demuestra por sí sola que tu CRM, portal o proceso interno haya completado su acción correctamente.

La segunda capa es el estado del recurso en Apification Cloud. La API REST cubre recursos de Cloud, carpetas, transformaciones, usuarios y webhooks dentro de una superficie autenticada. Para verificar estados concretos, la referencia expone lecturas como GET /cloud/services/{code}, GET /cloud/folders, GET /file-transformer/jobs/{id} y GET /webhooks/{id}/deliveries. La tercera capa es tu propio sistema: si ya creaste una carpeta espejo, guardaste un resultado, generaste un enlace o notificaste a un cliente, esa decisión debe quedar registrada en tu base de datos.

• Entrega: ¿llegó el evento y cómo respondió mi endpoint?
• Recurso: ¿qué estado tiene ahora el archivo, carpeta o job en Cloud?
• Negocio: ¿qué acción interna ya ejecuté y con qué resultado?

Qué debe registrar tu sistema para poder conciliar

El registro interno no necesita ser complejo, pero sí debe ser explícito. Como mínimo, guarda el identificador estable del evento o comando, el tipo de evento recibido, el recurso afectado, la acción prevista, el estado de procesamiento, el resultado aplicado y una marca de conciliación. Apification recomienda usar identificadores estables de evento y comando para evitar acciones de negocio duplicadas, y sus comandos idempotentes permiten adjuntar una clave estable a escrituras para que los reintentos de red no repitan la acción de negocio.

Un buen registro responde a cinco preguntas después de una caída: qué sabía el sistema, qué decidió hacer, qué alcanzó a hacer, qué comprobó después y qué falta. En línea con buenas prácticas de logging, evita guardar secretos o datos innecesarios; registra lo suficiente para reconstruir la secuencia sin convertir el log en una copia insegura del payload. La marca de conciliación puede ser simple: pendiente, verificado, corregido, descartado o requiere revisión humana.

• Evento recibido: identificador, fecha, tipo y recurso.
• Acción prevista: transformar, guardar resultado, crear enlace, notificar o actualizar estado interno.
• Resultado aplicado: éxito, fallo, omitido por duplicado o pendiente de verificación.
• Conciliación: fecha de revisión, estado confirmado y motivo de la decisión.

Patrón recomendado: aceptar rápido y procesar después

El receptor debe validar la firma HMAC antes de leer o persistir el payload. Después, debe aceptar el evento de forma durable y responder éxito solo cuando el payload verificado quedó guardado. Apification indica que el procesamiento largo debe continuar asincrónicamente. Esto evita que una transformación pesada, una consulta a un CRM o una operación de compartición bloquee la respuesta HTTP y provoque reintentos innecesarios.

El patrón operativo es recibir, validar, guardar, responder y procesar. La cola o tabla de trabajo posterior ejecuta la lógica de negocio con control de duplicados. Si el proceso falla a mitad de camino, no se pierde la evidencia del evento ni se añaden reintentos innecesarios por culpa de una tarea interna lenta. Además, este diseño facilita pausar consumidores, desplegar cambios y reanudar desde un punto conocido.

• Recibe el webhook en un endpoint mínimo y estable.
• Valida la firma antes de persistir el contenido.
• Guarda el evento y una clave de deduplicación.
• Responde éxito tras la aceptación durable, no tras todo el proceso de negocio.
• Ejecuta transformaciones, enlaces o actualizaciones internas en segundo plano.

Cuándo consultar la API para reconstruir el estado

No hace falta consultar la API en cada microdecisión si el flujo normal está sano. En producción, Apification plantea webhooks de finalización y fallo de transformación como alternativa a sondear continuamente, porque evitan solicitudes innecesarias y aportan una traza de eventos más clara. La consulta de conciliación tiene más valor después de incidentes: caída del consumidor, timeout prolongado, respuesta ambigua, despliegue interrumpido, evento fuera de orden o duda sobre el estado final de una transformación.

Para transformaciones, GET /file-transformer/jobs/{id} devuelve estado, progreso, uso y resultados del trabajo. Esto permite decidir si debes esperar, marcar fallo, guardar un resultado ya disponible o descartar una repetición. Para Cloud y carpetas, las lecturas de servicios y carpetas ayudan a comprobar si el recurso existe y cómo está organizado. Recuerda que mover un elemento en Apification Cloud cambia su organización, no su identidad; las propiedades y accesos siguen asociados al mismo item.

• Consulta tras una ventana de caída del consumidor.
• Consulta cuando el evento recibido contradice tu estado interno.
• Consulta cuando falte el evento de finalización de una transformación.
• Consulta antes de recrear carpetas, resultados o enlaces que podrían existir.
• No sustituyas todos los webhooks por polling continuo sin una razón operativa.

Cómo evitar duplicados al conciliar

La regla práctica es comparar antes de crear. Si vas a crear una carpeta, un enlace, una solicitud interna o una notificación, busca primero una decisión previa con la misma clave de negocio. Esa clave puede combinar el identificador del recurso Cloud, el identificador del job de transformación, el tipo de acción y el destinatario interno. El objetivo no es solo deduplicar eventos iguales, sino evitar que dos eventos distintos lleven a la misma acción de negocio.

Define estados terminales que no se reabren sin revisión: resultado compartido, transformación fallida confirmada, carpeta espejo creada, notificación enviada o acción descartada. Cuando una conciliación detecta que Cloud ya tiene el resultado y tu sistema ya lo compartió, marca el evento como verificado y no repitas. Cuando Cloud tiene el resultado pero tu sistema no lo compartió, ejecuta solo el paso pendiente. Cuando tu sistema dice que compartió, pero falta la evidencia esperada, deja el caso en revisión o reconstruye desde la API antes de crear otro recurso.

• Usa claves internas estables por acción de negocio, no solo por entrega HTTP.
• No crees un recurso nuevo si ya existe una decisión terminal equivalente.
• Distingue reintento técnico de nueva acción solicitada.
• Guarda el identificador del resultado o recurso creado cuando esté disponible.
• Prefiere completar el paso faltante antes que reiniciar todo el flujo.

Historial y estadísticas de webhooks: evidencia, no estado de negocio

GET /webhooks/{id}/deliveries devuelve un historial paginado de entregas de un endpoint de webhook. Esa vista es útil para saber si hubo múltiples intentos, qué código respondió tu receptor y qué cuerpo devolvió. En una investigación, puede explicar por qué un evento se procesó tarde o por qué se generó un reintento. También ayuda a contrastar la hora de entrega con tus propios logs y a detectar endpoints que responden éxito sin haber aceptado durablemente el payload.

Pero el historial de webhook no debe sustituir tu registro de decisiones. Un 200 en el endpoint significa, como mucho, que tu receptor aceptó el evento según su implementación; no prueba que una carpeta se haya creado en tu sistema interno, que una transformación se haya guardado como archivo Cloud o que un cliente haya recibido el enlace correcto. La conciliación madura une tres evidencias: delivery técnico, estado API del recurso y decisión interna persistida.

• Úsalo para diagnóstico de transporte y tiempos.
• Compáralo con tus logs de recepción y procesamiento.
• No lo uses como única prueba de acción de negocio completada.
• Investiga respuestas exitosas sin evento interno persistido.
• Investiga eventos persistidos sin acción terminal asociada.

Ejemplo operativo: archivo, transformación, enlace e interrupción

Imagina un portal de cliente conectado a Apification. Un usuario sube un archivo a Cloud, tu integración solicita una transformación y espera compartir el resultado. El File Transformer puede generar un resultado sin modificar el original, y ese resultado puede descargarse o guardarse como nuevo archivo Cloud para gestionarse, versionarse, descargarse o compartirse desde Cloud. El flujo normal registra el archivo de origen, el job, el resultado y la acción de compartición.

Ahora ocurre una interrupción: tu consumidor cae después de recibir un evento intermedio y vuelve veinte minutos más tarde. El proceso de recuperación no debe solicitar otra transformación de inmediato. Primero lee los eventos pendientes guardados, consulta el job con GET /file-transformer/jobs/{id}, verifica si existen resultados, revisa si tu registro interno ya tiene un enlace o acción de compartición terminal y, solo entonces, decide. Si el job terminó y no hay acción interna, guarda o comparte el resultado. Si ya se compartió, marca conciliado. Si el job falló, registra el fallo confirmado y evita repetir sin una nueva decisión de negocio.

• Paso 1: reanuda eventos persistidos, no confíes en memoria de proceso.
• Paso 2: verifica el job de transformación por API.
• Paso 3: compara con la decisión interna asociada al mismo recurso y acción.
• Paso 4: ejecuta solo la acción faltante.
• Paso 5: marca la conciliación con fecha, resultado y motivo.

Preguntas frecuentes