Webhooks de la API pública

Los Webhooks de la API pública son un servicio que te permite recibir notificaciones sobre cambios en tu cuenta, eliminando la necesidad de hacer consultas constantes a través de la API pública de Rentman.

En esencia, los webhooks son simplemente URLs a los que Rentman llama cada vez que se agrega, cambia o elimina algo en tu cuenta.

Piensa en ellos como notificaciones push para cada evento en tu cuenta, ya sea la adición de un nuevo proyecto, la edición de un contacto o la eliminación de un número de serie. Cuando ocurre alguno de estos eventos, Rentman enviará un payload a la URL que hayas establecido. Este payload contiene detalles sobre la entidad agregada, modificada o eliminada, junto con pistas sobre cómo recuperar más información de la API pública.

Nota: Utilizar webhooks requiere habilidades técnicas de programación y experiencia. Si te faltan estas habilidades, te recomendamos buscar ayuda de un desarrollador externo o una empresa. Ten en cuenta que nuestro equipo de soporte no está capacitado en este campo y no puede brindar asistencia con la implementación de webhooks.

Configuración de Webhooks de la API pública

  1. Para habilitar los webhooks, ve al módulo de Captura de pantalla 2023-11-23 a las 15.56.05.png Configuración y selecciona "Extensiones"
  2. Desplázate hacia abajo hasta la sección de Webhooks y haz clic en “Conectar”imagen-20231120-112332.png
  3. Aparecerá este pop-up:imagen-20231120-112310.pngAquí necesitas especificar URL y se te proporciona un Token. El campo de URL es donde especificas qué URL llamará Rentman cuando se cree, modifique o elimine algo en tu cuenta. El Token, en cambio, se utilizará para generar un resumen que deberá usarse del lado del cliente para verificar que el mensaje proviene de Rentman.
  4. Haz clic en “Guardar” y cierra el pop-up para habilitar los Webhooks.

Dominando los Webhooks de la API pública

Después de seguir todos los pasos anteriores, cuando se añade, modifica o elimina algo en tu cuenta, Rentman hará una llamada a la URL especificada. En este caso, se enviarán mensajes a https://mywebhookurl.com

Cada mensaje sigue un formato común. Para creaciones o actualizaciones, los mensajes se verán así:

{
"cuenta": "nombredecuenta",
"usuario": {
"tipoDeElemento": "Equipo",
"id": 33,
"ref": "/equipo/33"
},
"tipoDeEvento": "crear",
"tipoDeElemento": "Contacto",
"elementos": [
{
"id": 12014,
"ref": "/contactos/12014",
"padre": null
}
],
"fechaDeEvento": "2023-02-02T12:07:01+01:00"
}
Elementos más complejos, como Subproyectos o grupos de equipos planificados, pueden tener estructuras de mensajes más extensas, que incluirían referencias a elementos padres también.
{
"cuenta": "nombredecuenta",
"usuario": {
"tipoDeElemento": "Equipo",
"id": 33,
"ref": "/equipo/33"
},
"tipoDeEvento": "actualizar",
"tipoDeElemento": "NúmeroDeSerie",
"elementos": [
{
"id": 8367,
"ref": "/numerosdeserie/8367",
"padre": {
"id": 12792,
"tipoDeElemento": "Equipo",
"ref": "/equipo/12792"
}
}
],
"fechaDeEvento": "2023-02-02T12:03:25+01:00"
}
Cuando se elimina un elemento, el mensaje contiene detalles ligeramente diferentes en su sección de elementos:
{
"cuenta": "nombredecuenta",
"usuario": {
"tipoDeElemento": "Equipo",
"id": 33,
"ref": "/equipo/33"
},
"tipoDeEvento": "eliminar",
"tipoDeElemento": "PersonaDeContacto",
"elementos": [
10,
31
],
"fechaDeEvento": "2023-02-02T12:08:00+01:00"
}

El payload siempre contendrá estos componentes:

  • cuenta - nombre de la cuenta desde la que se origina el mensaje
  • usuario - id y referencia de la API pública al empleado que inició el cambio. Puede ser nulo para acciones no realizadas por usuarios, como cuando un documento se firma digitalmente
  • tipoDeEvento - crear, actualizar o eliminar
  • tipoDeElemento - tipo del elemento que se creó, actualizó o eliminó. Los posibles tipos de elementos son:
Posibles tipos de elementos
  • Cita, Equipo de Cita, Accesorio, Ubicación de Stock, Disponibilidad de Equipo, Línea de Factura, Contacto, Contrato, Costo de Proyecto, Número de Serie, Factuur, Archivo, Carpeta, Función de Proyecto, Grupo de Funciones de Proyecto, Actividad de Registro de Tiempo, Libro Mayor, Subalquiler, Grupo de Equipos de Subalquiler, Equipo de Subalquiler, Equipo, Grupo de Equipos de Proyecto, Equipo de Personal, Cotización, Persona de Contacto, Equipo de Proyecto, Vehículo de Proyecto, Equipo de Proyecto, Proyecto, Solicitud de Proyecto, Equipo de Solicitud de Proyecto, Tarifa de Personal, Factor de Tarifa de Personal, Reparación, Escaneo de Almacén, Escáner de Almacén, Contenido de Conjunto de Equipos, Estado, Subproyecto, Clase de Impuesto, Tipo de Proyecto, Registro de Tiempo, Vehículo, Movimiento de Stock

Consejo de Rentman: Puedes añadir el valor "ref" para consultar fácilmente al usuario que activó el webhook, simplemente añadiéndolo después de la URL base de la API https://api.rentman.net. De la misma manera, puedes hacer lo mismo con el valor "ref" de cada elemento en el payload.

  • elementos - Para creaciones y actualizaciones, el mensaje contiene una matriz de objetos, donde cada objeto representa un elemento creado/actualizado. El objeto contiene el ID del elemento, la referencia de la API pública y también un objeto anidado de la misma estructura, apuntando al padre, si existe. Si no hay un padre, el valor de padre es igual a null. Para eliminaciones, elementos es una matriz de enteros, que contiene los IDs de los elementos que fueron eliminados
  • fechaDeEvento - fecha y hora en que ocurrió el evento

Validación de la autenticidad del payload del webhook

/* ejemplo de cómo se ve un encabezado de Digest:
Digest: sha512=509072eee2c11804287bf807307ed360892053dde89c15ddacd9daa24c63c492963c089d54677598df4422f7d18cbd6a8ebca689841754e8ca44aee1054ddf0c
*/

// este es el cuerpo completo de la solicitud
$raw_body = file_get_contents('php://input');

// dividir el valor en '='
$digestParts = explode('=', $_SERVER['HTTP_DIGEST']);
$algo = digestParts[0];
$digest = digestParts[1];

// Esto es conocido por el cliente y Rentman solamente
$token= 'some_secret_key';
$clientGeneratedDigest = hash_hmac($algo, $raw_body, $token, false);

if($digest === $clientGeneratedDigest){
// La llamada de webhook fue realizada por Rentman
}
else{
// La llamada de webhook no fue realizada por Rentman
}
¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 0

Artículos en esta sección