Las capturas muestran la interfaz en inglés y una prueba local controlada con identificadores sintéticos. Sustituye el dominio de ngrok por el tuyo. No se creó ni reprodujo una conversación de cliente para estas pruebas.
Antes de empezar
Necesitas acceso de administrador, un receptor bajo tu control y una dirección HTTPS pública en el puerto 443. No se admitenlocalhost:3000, HTTP, direcciones privadas ni destinos que solo tengan IPv6. Para desarrollo local, usa un túnel HTTPS.
Si aparecen avisos de configuración de firma, trabajador no disponible o entregas no habilitadas para el espacio, contacta con tu administrador de Visito. Habilitado describe la configuración del endpoint; no demuestra que las entregas funcionen. Crear un endpoint requiere un trabajador compatible y configuración de firma; enviar pruebas también requiere que el espacio esté habilitado para entregas.
1. Iniciar un receptor local
El ejemplo completo en Python verifica la firma sobre los bytes exactos, comprueba la fecha, guarda los eventos aceptados en SQLite y elimina duplicados por ID de evento. Requiere Python 3.10 o posterior y solo usa la biblioteca estándar. Desde el directorio del ejemplo:503. WEBHOOK_FAIL_FIRST=1 devuelve intencionalmente 503 a la primera solicitud correctamente firmada de cada evento y acepta el reintento. Omítelo para aceptar normalmente.
En otra terminal, inicia tu cliente ngrok ya configurado:
ngrok http 8765 --url=TU-DOMINIO. El destino del webhook será:
2. Crear el webhook
- En el espacio correcto, abre Desarrolladores → Webhooks y selecciona Crear webhook (Create webhook en las capturas).
- Introduce un Nombre reconocible y el Destino HTTPS completo, incluido
/webhooks/visitopara este ejemplo. - Selecciona los eventos necesarios. Para esta prueba, elige solo
message.created. - Selecciona Guardar webhook.
- Copia y guarda el secreto inmediatamente. Solo se muestra una vez. No hay selector de claves de API.
Eventos disponibles
Los eventos reales contienen metadatos, como IDs y cambios de estado, no cuerpos de conversaciones. Consulta contenido con la API y sus permisos. Se excluyen turnos internos de sistema/herramientas y mensajes de Playground.
3. Enviar un evento de prueba
Abre el endpoint guardado, selecciona Enviar evento de prueba (Send test event), elige un evento suscrito y revisa el contenido y el destino. Selecciona Confirmar una vez.
schemaVersion: "1.0" y añaden test: true. Los IDs de recursos son sintéticos; no se crea ningún mensaje, conversación ni registro de CRM. Tu receptor sí recibe una solicitud HTTPS real: evita que los eventos de prueba ejecuten acciones de negocio.
Se requiere un endpoint activo y autorizado, y un trabajador listo. El límite es una prueba por endpoint por minuto. El dashboard utiliza una clave de idempotencia para evitar duplicar la creación de la misma solicitud. Espera el resultado en lugar de confirmar repetidamente.
4. Revisar entregas e intentos
En Entregas (Deliveries), selecciona la prueba. El detalle muestra ID de evento, ID de entrega, JSON, estado, siguiente reintento cuando corresponde e intentos individuales. Filtra por estado, evento, Prueba/Real e historial. El rango predeterminado es de siete días, con opciones hasta 30 días. En este ejemplo, el intento 1 responde503 intencionalmente. La entrega permanece Pendiente y Visito programa otro intento aproximadamente un minuto después. Cuando recibe 204, pasa a Entregado. Ambos intentos comparten el mismo ID de evento.
http://127.0.0.1:8765 localmente para ver las verificaciones del receptor. Esta página de diagnóstico no se sirve a través del dominio público de ngrok.
Usa Actualizar para renovar la lista. Una entrega pendiente abierta se actualiza como máximo cada diez segundos; se detiene al finalizar, ocultar la página o cerrar el panel. Puedes copiar la URL para compartir el endpoint o la entrega con otro administrador autorizado.
Cada intento muestra inicio, duración, código HTTP cuando existe y motivo de fallo seguro. No se almacenan cuerpos de respuesta, encabezados arbitrarios, firmas ni secretos. Los registros antiguos pueden indicar que no se guardó el historial de intentos. Los intentos y la actividad se conservan 30 días; los metadatos de entregas terminadas, 30 días después de su finalización.
Reintentos y duplicados
Hay un intento inicial y seis reintentos, con esperas de 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas y 24 horas después de fallos sucesivos. Cada intento tiene un límite de diez segundos. Las colas y la recuperación pueden añadir demora. No se siguen redirecciones. La entrega es al menos una vez y no garantiza orden. Verifica cada solicitud y deduplica de forma persistente poreventId. Reintentar entrega solo está disponible para fallos terminales: inicia otro ciclo conservando el ID de evento y el historial previo. No evita la deduplicación del receptor.
El servicio limita los envíos simultáneos a diez en total y dos por espacio. Responde 2xx después de aceptar el evento de forma persistente; procesa el trabajo costoso por separado.
Verificar firmas en tu aplicación
Lee estos encabezados:timestamp + "." + rawBody. Compara en tiempo constante y rechaza diferencias de más de cinco minutos. Verifica antes de interpretar JSON, conserva los bytes exactos y sincroniza el reloj. Comprueba que el ID del encabezado coincida con el evento y deduplica de forma persistente.
No uses un parser que transforme el cuerpo antes de verificarlo. No autentiques solo por la URL de destino. La referencia en inglés incluye un verificador JavaScript; el ejemplo Python combina verificación y aceptación persistente.
Administrar configuración y autorización
En Configuración (Settings) puedes cambiar nombre, destino, eventos y estado habilitado. Actividad (Activity) muestra el historial de cambios sin secretos.
Las suscripciones administradas desde el dashboard pertenecen al espacio. La salida del administrador creador o la expiración de su sesión no detienen las entregas. Las administran los administradores actuales del espacio.
Las suscripciones vinculadas a credenciales, creadas mediante API, dependen de los permisos, vencimiento y revocación de su credencial. Los registros anteriores conservan este comportamiento. Los administradores pueden revisar y editar ambos tipos; una edición ordinaria desde el dashboard no cambia el modo.
Transferir a administración del dashboard solicita confirmar que una futura revocación de la credencial ya no detendrá las entregas. Conserva destino, secreto, IDs de evento e historial, y registra actor y fecha. No existe transferencia inversa en esta versión.
Los clientes de API siguen necesitando permisos de webhooks y de lectura de los eventos afectados para modificar suscripciones administradas desde el dashboard. No las vinculan silenciosamente a su credencial. Consulta el contrato de API.
Solución de problemas
Terminar la prueba local
Deshabilita el webhook y confirma su estado antes de detener el receptor o ngrok. Así no queda un endpoint habilitado apuntando a una computadora desconectada. Conserva el historial para revisarlo. Detén ambos procesos con Ctrl+C y elimina el secreto local cuando ya no lo necesites.
503 controlado y recuperación automática a 204 con el mismo ID. Por sí sola no verifica captura de eventos reales, todos los casos de error ni rendimiento de producción del receptor.