Saltar al contenido
ComdigDocs

Webhooks entrantes

Enviar eventos

Recibe un evento de tu sistema y, según la conexión configurada en Comdig, envía una plantilla de WhatsApp al cliente. Esta llamada no usa X-API-Key: se autentica con la firma X-Comdig-Signature.

Solicitud#

POSThttps://api.comdig.co/v1/inbound-webhook

Autenticación: firma en el header X-Comdig-Signature. Esta llamada no usa X-API-Key.

Headers#

  • X-Comdig-SignaturestringRequerido

    t=<unix_seconds>,v1=<firma>, donde firma = hex(HMAC-SHA256(secreto, t + "." + cuerpo_crudo)). Vence si t difiere más de 300 segundos de la hora del servidor. Se aceptan varios v1= (útil al rotar el secreto).

  • Content-TypestringRequerido

    application/json

Parámetros de consulta#

  • cstringRequerido

    connection_id (UUID) de la conexión. Se obtiene al crearla en Comdig → API y webhooks → Webhooks entrantes.

Parámetros del cuerpo#

  • event_idstring | numberRequerido

    Identificador único del evento en tu sistema. Si llega dos veces el mismo event_id en la misma conexión, Comdig no lo vuelve a procesar y responde duplicate: true, así que reintentar es seguro.

    Máx. 200 caracteres

  • …any

    El resto del JSON es libre. En Comdig configuras la ruta de cada dato con notación de puntos e índices (p. ej. cliente.telefono, items.0.nombre): teléfono (obligatorio, mín. 7 dígitos), nombre (opcional) y una ruta por cada variable de la plantilla.

  • event_typestring

    Tipo de evento. La conexión puede filtrar qué tipos procesa (lista separada por comas o *).

    Por defecto: sin_tipoMáx. 100 caracteres

Ejemplo#

Factura emitida
secret="$COMDIG_WEBHOOK_SECRET"
body='{"event_id":"fac-1001","event_type":"factura_emitida","cliente":{"nombre":"Ana Gómez","telefono":"+573001234567"},"factura":{"numero":"FV-1001","total":"120.000"}}'
t=$(date +%s)
firma=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$secret" -hex | awk '{print $NF}')

curl -X POST "https://api.comdig.co/v1/inbound-webhook?c=$COMDIG_CONNECTION_ID" \
  -H "Content-Type: application/json" \
  -H "X-Comdig-Signature: t=$t,v1=$firma" \
  --data-binary "$body"

Respuestas#

  • 200Recibido; la plantilla se envía en segundo plano.

    JSON
    {
      "received": true,
      "event_id": "fac-1001"
    }
  • 200Ya se había recibido ese event_id.

    JSON
    {
      "received": true,
      "duplicate": true,
      "event_id": "fac-1001"
    }
  • 400El cuerpo no es JSON válido.

    JSON
    {
      "error": "invalid_json"
    }
  • 400Falta event_id.

    JSON
    {
      "error": "event_id_required"
    }
  • 401Falta el header X-Comdig-Signature.

    JSON
    {
      "error": "firma_ausente"
    }
  • 401t difiere más de 300 segundos de la hora del servidor.

    JSON
    {
      "error": "firma_vencida"
    }
  • 401La firma no coincide.

    JSON
    {
      "error": "firma_invalida"
    }
  • 404El parámetro c es inválido o la conexión no existe.

    JSON
    {
      "error": "invalid_connection"
    }
  • 405Usa POST.

    JSON
    {
      "error": "method_not_allowed"
    }
  • 409La conexión está pausada en Comdig.

    JSON
    {
      "error": "connection_paused"
    }
  • 500Error temporal: reintenta.

    JSON
    {
      "error": "storage_failed"
    }

Procesamiento#

Después de responder 200, Comdig:

  • Ignora los tipos de evento que la conexión no tiene configurados.
  • No envía si falta el teléfono o alguna variable: nunca envía plantillas con huecos.
  • Si el envío falla, reintenta hasta 5 intentos en 24 horas, con esperas de 10, 20, 40 y 80 minutos.

Reintentos desde tu sistema#

  • Ante un 5xx o un error de red, reintenta con backoff exponencial.
  • No reintentes un 4xx sin corregir la causa. La excepción es 409: reintenta cuando reactives la conexión.
  • Reintenta siempre con el mismo event_id: si ya se había recibido, Comdig responde duplicate: true y no lo procesa de nuevo.

Cómo calcular la firma: Verificar la firma.