Los webhooks de la API pública son un servicio que te permite recibir notificaciones sobre cambios en la cuenta, sin necesidad de realizar constantemente consultas a través de la API pública de Rentman.

Básicamente, los webhooks son URL a las que Rentman consulta cada vez que se añade, modifica o elimina algo en tu cuenta.

Considérelas notificaciones push para cada evento de la cuenta, ya sea la creación de un nuevo proyecto, la edición de un contacto o la eliminación de un número de serie. Cuando se produzca cualquiera de estos eventos, Rentman enviará una carga útil a la URL que hayas configurado. Esta carga útil contiene detalles sobre la entidad añadida, modificada o eliminada, junto con sugerencias sobre cómo recuperar más información de la API pública.

Nota: el uso de webhooks requiere conocimientos técnicos de programación y experiencia. Si no los tienes, te recomendamos que solicites ayuda a un desarrollador o empresa externa. Ten en cuenta que nuestro equipo de soporte no tiene la formación necesaria para proporcionar asistencia con la aplicación de webhooks.

Configuración de los webhooks de la API pública

1. Para activar los webhooks, dirígete al módulo Configuración y selecciona «Extensiones».
2. Desplázate hasta la sección Webhooks y haz clic en «Conectar».
   
3. Aparecerá esta ventana emergente:
   Aquí necesitas especificar la URL y se te proporciona un token. En el campo de la URL se especifica la URL a la que Rentman consultará cuando se cree, modifique o elimine algo en tu cuenta. El token, en cambio, se utilizará para generar un resumen con el que el cliente verificará que el mensaje procede de Rentman.
4. Haz clic en «Guardar»y cierra la ventana emergente para activar los webhooks.

Dominar los webhooks de la API pública

Una vez seguidos todos los pasos anteriores, cuando se añada, modifique o elimine algo en tu cuenta, Rentman consultará 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 seguirán este modelo:

{
  "account": "youraccountname",
  "user": { 
    "itemType": "Crew",
    "id": 33,
    "ref": "/crew/33"
  },
  "eventType": "create", 
  "itemType": "Contact", 
  "items": [ 
    {
        "id": 12014,
        "ref": "/contacts/12014",
        "parent": null
    }
  ],
  "eventDate": "2023-02-02T12:07:01+01:00"
}

{
  "account": "youraccountname",
  "user": {
      "itemType": "Crew",
      "id": 33,
      "ref": "/crew/33"
  },
  "eventType": "update",
  "itemType": "SerialNumber",
  "items": [
    {
        "id": 8367,
        "ref": "/serialnumbers/8367",
        "parent": {
            "id": 12792,
            "itemType": "Equipment",
            "ref": "/equipment/12792"
        }
    }
  ],
  "eventDate": "2023-02-02T12:03:25+01:00"
}

{
  "account": "youraccountname",
  "user": {
      "itemType": "Crew",
      "id": 33,
      "ref": "/crew/33"
  },
  "eventType": "delete",
  "itemType": "ContactPerson",
  "items": [
      10,
      31
  ],
  "eventDate": "2023-02-02T12:08:00+01:00"
}

/* ejemplo del aspecto de una cabecera de resumen:
Digest: sha512=509072eee2c11804287bf807307ed360892053dde89c15ddacd9daa24c63c492963c089d54677598df4422f7d18cbd6a8ebca689841754e8ca44aee1054ddf0c
*/

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

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

// Esto lo conocen solo el cliente y Rentman
$token= 'some_secret_key';
$clientGeneratedDigest = hash_hmac($algo, $raw_body, $token, false);

if($digest === $clientGeneratedDigest){
// Rentman realizó la consulta del webhook
}
else{
// Rentman no realizó la consulta del webhook
}

Limitaciones conocidas

Con la implementación actual de webhooks, hay dos limitaciones a tener en cuenta:

• Entrega duplicada de webhooks: en raras ocasiones, pueden enviarse varios webhooks para el mismo evento. Esto ocurre con poca frecuencia, pero es posible.
• Orden de entrega: es posible que el orden de entrega de los webhooks no siempre refleje la secuencia exacta de los eventos tal y como se produjeron en Rentman. Aunque estos casos son poco comunes, pueden ocurrir.

¿Qué hago si la URL del webhook no responde?

Si la URL del webhook deja de responder, ya sea por una configuración incorrecta o por problemas con el endpoint, Rentman ha implementado un sistema de notificaciones para ayudar a resolver la situación.

¿Qué significan estas notificaciones?

Estas notificaciones solo son visibles para los miembros del personal con acceso al módulo settingsConfiguración. Asegúrate de que los miembros adecuados de tu personal tienen acceso a este módulo para mantenerse informados y resolver cualquier problema a tiempo.

Para resolver estos problemas, puedes volver a habilitar los webhooks actualizando la URL en la sección Webhooks del módulo settings Configuración, de la misma forma que lo harías al habilitar los webhooks por primera vez.

[GIF aquí]

Consejo de Rentman: no olvides proporcionar una URL válida y operativa para garantizar la entrega ininterrumpida de los webhooks.