Webhooks

Usa esta referencia cuando un sistema externo publica eventos hacia Convertmax por HTTP.

Ruta

Convertmax admite tráfico de webhook entrante en:

• POST /ingest/inbound/:sourceConfigId

sourceConfigId apunta a una configuración de webhook entrante guardada que define:

• el tipo de fuente
• la configuración de autenticación
• el comportamiento opcional de override del tipo de evento

Tipos de fuente entrante admitidos

webhook

Usa este tipo de fuente para payloads de webhook JSON autenticados que no necesitan un parser específico de proveedor.

Patrones de autenticación admitidos:

• Authorization: Bearer <token>
• verificación HMAC opcional con x-convertmax-signature cuando hay un secreto de firma configurado

Forma típica del payload:

{
  "inbound_event_id": "evt_123",
  "event_type": "lead.updated",
  "payload": {
    "lead_id": "lead_42",
    "status": "qualified"
  }
}

make

Usa este tipo de fuente cuando un escenario de Make.com llama a Convertmax con un módulo HTTP. El parseo y la autenticación coinciden con webhook; source_type se registra como make para metadatos de enrutamiento y auditoría.

segment

Usa este tipo de fuente cuando envías payloads de eventos con formato Segment directamente a Convertmax.

Patrón de autenticación admitido:

• Authorization: Bearer <token>

Formas admitidas:

• eventos individuales estilo Segment como track, identify o page
• payloads de lote (batch) estilo Segment usando batch: []

Forma normalizada del evento entrante

Después de la autenticación y el parseo, Convertmax estandariza el tráfico entrante en una forma de evento interna con campos que incluyen:

• inbound_event_id
• source_config_id
• source_type
• provider_event_id
• event_type
• received_at
• payload
• headers
• meta

Protección de volumen

El límite de tasa (rate limiting) se aplica antes de encolar.

Comportamiento:

• los límites se cuentan en eventos normalizados
• los payloads de lote consumen una unidad por cada elemento del evento
• las solicitudes de webhook siguen devolviendo HTTP 200
• la protección de volumen interna sigue controlando cómo se manejan las solicitudes detrás de escena

Manejo de duplicados

El manejo de duplicados se aplica en el consumidor de la cola entrante.

Comportamiento:

• Convertmax comprueba (inbound_event_id, source_config_id) antes de procesar
• si ese par ya existe en el almacén de eventos procesados, el evento se omite
• si el procesamiento tiene éxito, Convertmax archiva el resultado, escribe un recibo y luego marca el evento como procesado

Este orden garantiza que un evento no se marque como procesado antes de que se escriba su registro de auditoría.

Confirmaciones de entrega

Las solicitudes de webhook entrantes ahora devuelven HTTP 200.

Una respuesta exitosa significa que:

• la solicitud se autenticó
• la normalización tuvo éxito
• el payload del evento fue aceptado para su encolado

No significa necesariamente que el procesamiento de negocio posterior ya se haya completado.

Documentación relacionada

• Compatibilidad con Segment