Configurar webhooks de Camtom: Notificaciones automáticas en tiempo real

Qué son los webhooks y por qué usarlos

Un webhook es una llamada HTTP que Camtom envía automáticamente a tu servidor cuando ocurre un evento relevante: un pedimento fue prevalidado, una clasificación se completó, una MVE fue firmada, o un documento fue procesado. En lugar de hacer polling constante a la API para verificar cambios, los webhooks te notifican en tiempo real, reduciendo la latencia y el consumo de recursos.

Paso 1: Crear un endpoint en tu servidor

Tu endpoint debe ser una URL pública accesible por HTTPS que acepte solicitudes POST. El endpoint debe responder con un código HTTP 200 dentro de 5 segundos para confirmar la recepción. Si no responde o devuelve un error, Camtom reintentará el envío hasta 5 veces con backoff exponencial (1, 5, 30, 120 y 600 segundos).

Paso 2: Registrar el webhook en Camtom

Desde tu panel de Camtom, navega a Configuración → Webhooks → Nuevo webhook. Ingresa la URL de tu endpoint, selecciona los eventos que quieres recibir y genera un signing secret. Camtom firmará cada solicitud con este secret usando HMAC-SHA256 para que puedas verificar la autenticidad del mensaje.

Paso 3: Seleccionar los eventos a monitorear

• pedimento.created: Se creó un nuevo pedimento en TIM.
• pedimento.validated: Un pedimento pasó la prevalidación sin errores.
• pedimento.paid: Se registró el pago de un pedimento.
• classification.completed: TariffPro completó la clasificación de un producto o lote.
• document.processed: Docs terminó de procesar un documento subido.
• mve.signed: Una MVE fue firmada y enviada a VUCEM exitosamente.
• mve.rejected: VUCEM rechazó una MVE — requiere corrección.
• kyb.expiring: Un documento del expediente KYB está próximo a vencer.

Paso 4: Procesar los eventos recibidos

Cada webhook contiene un JSON con el tipo de evento, la fecha, el ID del recurso afectado y los datos relevantes. Procesa los eventos de forma asíncrona: recibe el webhook, responde 200 inmediatamente, y luego procesa la lógica de negocio en segundo plano. Esto evita timeouts y garantiza que Camtom marque el envío como exitoso.

Paso 5: Probar y monitorear

Usa el botón Enviar evento de prueba en la configuración del webhook para verificar que tu endpoint lo recibe correctamente. El log de webhooks en Camtom muestra los últimos 100 envíos con su código de respuesta, tiempo de respuesta y cuerpo de la solicitud. Si un webhook falla repetidamente, Camtom lo desactivará automáticamente y te notificará por correo.

1. Usa HTTPS obligatoriamente — los webhooks no se envían a URLs HTTP.
2. Verifica la firma HMAC-SHA256 en cada solicitud recibida.
3. Responde con HTTP 200 dentro de 5 segundos para confirmar la recepción.
4. Procesa la lógica de negocio de forma asíncrona después de confirmar la recepción.
5. Monitorea el log de webhooks para detectar fallos y corregirlos rápidamente.