/m2m/v1. Envía Authorization: Bearer <clave>. La clave determina el tenant.
Los administradores también pueden crear y administrar webhooks desde el dashboard con su sesión normal, sin clave de API. Los webhooks de acciones Capturar datos se configuran por separado en Acciones.
Crear una suscripción
POST /webhooks requiere webhooks:write y el permiso de lectura de cada recurso seleccionado:
secret devuelto: aparece solo al crear o rotar. GET /webhooks lista suscripciones. GET/PATCH/DELETE /webhooks/{subscriptionId} consulta, modifica o elimina. La creación también acepta name opcional; PATCH acepta name, url, events y active. POST /webhooks/{subscriptionId}/rotate-secret rota el secreto.
El evento contiene
eventId, type, schemaVersion:"1.0", tenantId, occurredAt y data. Los datos incluyen IDs, dirección/canal o cambios de estado/revisión. Consulta contenido con los GET autorizados. Se excluyen turnos internos y mensajes del playground.
Verificar la firma
Encabezados:X-Visito-Event-Id y X-Visito-Signature: t=<segundos-unix>,v1=<hmac-hex>.
Calcula HMAC-SHA256 de timestamp + "." + cuerpoOriginal usando el secreto. Compara en tiempo constante, rechaza diferencias de más de cinco minutos y deduplica por eventId. Verifica los bytes originales antes de interpretar JSON.
Entrega y recuperación
La entrega es al menos una vez y no garantiza orden. Devuelve 2xx después de aceptar durablemente el evento. No se siguen redirecciones. El destino debe usar HTTPS público en puerto 443 y DNS con IPv4 pública; no se admiten destinos locales, privados, reservados o solo IPv6. Se valida DNS y se fija la dirección de conexión en cada intento. Cada intento tiene 10 segundos. Los errores se reintentan después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas y 24 horas: siete intentos en total. Conwebhooks:read, consulta GET /webhooks/{subscriptionId}/deliveries y su detalle /{deliveryId}. Para reiniciar un fallo agotado, usa POST /webhooks/{subscriptionId}/deliveries/{deliveryId}/retry; conserva eventId. Los metadatos se guardan 30 días después de terminar.
Autorización y administración desde el dashboard
Las suscripciones creadas mediante API están vinculadas a credenciales: revocar, vencer o reducir los permisos de su clave cancela entregas pendientes. Los registros antiguos sin modo explícito conservan esta regla. Actualizarlas mediante API las vincula a la credencial que llama y vuelve a exigir los permisos de lectura de eventos. Las creadas desde el dashboard son administradas por el espacio de trabajo. No dependen de la sesión, permanencia del creador ni clave de API. Las gestionan los administradores actuales. Los clientes API pueden modificarlas con los permisos de webhooks y lectura de todos los eventos afectados; conservan ese modo y no adjuntan la credencial que llama. Los cuerpos de solicitudes ordinarias no pueden elegir ni cambiar el modo de autorización. Un administrador puede Transferir a administración del dashboard tras confirmar que revocar la credencial después ya no detendrá entregas. Se conservan destino, secreto, IDs e historial; se registran actor y fecha. No se reproducen entregas canceladas ni existe transferencia inversa. Desactivar o eliminar cualquiera de los tipos cancela entregas en cola. Una solicitud en curso puede terminar. Reactivar no reenvía cancelaciones. Rotar el secreto aplica inmediatamente a futuros intentos. El dashboard ofrece historial de intentos, actividad y eventos sintéticos. Las pruebas usan el sobre 1.0 contest:true, llegan a una sola suscripción por la entrega normal y no crean registros de negocio. Requieren endpoint activo, espacio habilitado y trabajador listo; el límite es una prueba por endpoint por minuto. Consulta la guía ilustrada.
En automatizaciones de respuesta, procesa solo message.created con data.direction=inbound. Persiste eventId y usa un Idempotency-Key estable al responder para evitar duplicados y bucles.