Saltar al contenido principal
Los webhooks envían solicitudes HTTP POST a tu servidor cuando ocurren eventos específicos en Quikly. Úsalos para sincronizar con tu CRM, disparar flujos de n8n, enviar notificaciones a Slack o construir automatizaciones personalizadas.

​
Crear un webhook

Puedes crear webhooks desde la interfaz de Quikly o a través de la API.

​
Desde la interfaz

Ve a Configuración → Webhooks y haz clic en Crear Webhook. Ingresa un nombre, la URL de tu endpoint y selecciona los eventos a los que quieres suscribirte.

​
Desde la API

curl -X POST "https://api.getquikly.com/api/external/v1/webhooks" \
  -H "X-API-Key: qk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "url": "https://your-server.com/webhooks/quikly",
    "events": ["proposal.created", "proposal.shared", "proposal.accepted"]
  }'
La respuesta incluye un campo secret que se muestra solo una vez. Guárdalo inmediatamente — lo necesitas para verificar las firmas de los webhooks.

​
Eventos disponibles

EventoSe dispara cuando
proposal.createdSe crea una nueva propuesta
proposal.updatedSe modifica una propuesta (requerimientos, configuración, precios)
proposal.sharedSe comparte una propuesta con un cliente vía enlace
proposal.acceptedUn cliente acepta una propuesta
proposal.rejectedUn cliente rechaza una propuesta
proposal.revision_requestedUn cliente solicita cambios a una propuesta
lead_session.createdSe inicia una nueva sesión de lead (desde widget, Telegram o API)
lead_session.updatedCambia el estado de una sesión de lead (ej., recopilando info → propuesta lista)
Puedes suscribirte a eventos específicos o escuchar todos incluyendo cada evento en el array events.

​
Formato del payload

Cada entrega de webhook envía un payload JSON con esta estructura: 
{
  "event": "proposal.accepted",
  "timestamp": "2026-04-03T14:30:00Z",
  "webhook_id": "wh_abc123",
  "data": {
    "proposal_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Cloud Migration - Acme Corp",
    "status": "accepted",
    "client_name": "John Smith",
    "total": 24500.00,
    "currency": "USD",
    "share_url": "https://app.getquikly.com/p/abc123token",
    "responded_at": "2026-04-03T14:30:00Z"
  }
}
Para eventos de lead_session, el objeto data contiene campos de la sesión como channel, channel_id, client_name, brief y status.

​
Headers HTTP

Cada solicitud de webhook incluye estos headers:
HeaderDescripción
X-Quikly-EventTipo de evento (ej., proposal.accepted)
X-Quikly-SignatureDigest hex HMAC-SHA256 del cuerpo de la solicitud
X-Quikly-TimestampMarca de tiempo Unix de cuándo se envió el webhook
X-Quikly-Webhook-IdID de la configuración del webhook
Content-TypeSiempre application/json

​
Verificar firmas

Cada webhook está firmado con el secret que recibiste al crearlo. Verifica el header X-Quikly-Signature para confirmar que la solicitud proviene de Quikly. 
import hmac
import hashlib

def verify_webhook(payload_body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
Verifica siempre las firmas antes de procesar los payloads de webhooks. Esto evita que atacantes envíen eventos falsos a tu endpoint.

​
Política de reintentos

Si tu endpoint devuelve un código de estado no-2xx o expira el tiempo (límite de 10 segundos), Quikly reintenta la entrega con backoff exponencial:
IntentoDemora
1er reintento30 segundos
2do reintento2 minutos
3er reintento15 minutos
4to reintento1 hora
5to reintento4 horas
Después de 5 reintentos fallidos, la entrega se marca como fallida. Puedes ver todos los intentos en los logs de webhooks.

​
Probar un webhook

Envía un evento de prueba para verificar que tu endpoint es accesible: 
curl -X POST "https://api.getquikly.com/api/external/v1/webhooks/{webhook_id}/test" \
  -H "X-API-Key: qk_your_api_key_here"
El payload de prueba usa el tipo de evento test y contiene datos de ejemplo. Tu endpoint debe devolver un código de estado 200.

​
Ver logs de entrega

Consulta entregas recientes y depura fallos: 
curl "https://api.getquikly.com/api/external/v1/webhooks/{webhook_id}/logs" \
  -H "X-API-Key: qk_your_api_key_here"
Cada entrada del log incluye el código de estado HTTP, cuerpo de la respuesta, tiempo de respuesta y el payload completo que se envió. También puedes ver los logs en la interfaz de Quikly en Configuración → Webhooks → (seleccionar webhook) → Logs.

​
Gestión de webhooks

OperaciónEndpoint de APIRuta en la interfaz
Listar todos los webhooksGET /webhooksConfiguración → Webhooks
Actualizar eventos o URLPUT /webhooks/{id}Clic en webhook → Editar
Pausar entregasPUT /webhooks/{id} con is_active: falseInterruptor de toggle
EliminarDELETE /webhooks/{id}Clic en webhook → Eliminar
Regenerar secretPOST /webhooks/{id}/regenerate-secret (solo interfaz)Clic en webhook → Regenerar