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#
Autenticación: firma en el header X-Comdig-Signature. Esta llamada no usa X-API-Key.
Headers#
X-Comdig-SignaturestringRequeridot=<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-TypestringRequeridoapplication/json
Parámetros de consulta#
cstringRequeridoconnection_id (UUID) de la conexión. Se obtiene al crearla en Comdig → API y webhooks → Webhooks entrantes.
Parámetros del cuerpo#
event_idstring | numberRequeridoIdentificador ú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
…anyEl 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_typestringTipo de evento. La conexión puede filtrar qué tipos procesa (lista separada por comas o *).
Por defecto: sin_tipoMáx. 100 caracteres
Ejemplo#
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
5xxo un error de red, reintenta con backoff exponencial. - No reintentes un
4xxsin corregir la causa. La excepción es409: reintenta cuando reactives la conexión. - Reintenta siempre con el mismo
event_id: si ya se había recibido, Comdig respondeduplicate: truey no lo procesa de nuevo.
Cómo calcular la firma: Verificar la firma.