In essence, webhooks are simply URLs that get called by Rentman, whenever something is added, changed or deleted in your account.

Think of them as push notifications for every event in your account—whether it's a new project being added, a contact being edited, or a serial number being deleted. When any of these events occur, Rentman will post a payload to the URL you've set. This payload contains details about the added, modified, or deleted entity, along with hints on how to retrieve more information from the Public API.

Setting up public API webhooks

1. To enable webhooks, go to the Configuration module and select "Integrations"
2. Scroll down to Webhooks section and click “Connect”
3. This pop-up will appear:Here you need to specify URL and you are given a Token. The URL field is where you specify which URL will be called by Rentman when something is created, modified, or deleted on your account. The Token, instead, will be used for generating a digest that should be used client-side to verify that the message originates from Rentman.
4. Click “Save” and close the pop-up to enable Webhooks.

Mastering public API webhooks

After all the above steps are followed, when something is added, modified, or deleted in your account, Rentman will make a call to the specified URL. In this case, messages will be sent to https://mywebhookurl.com. 

Each message follows a common format. For creates or updates, messages will look like this:

{
  "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"
}

/* example what a Digest header looks:
Digest: sha512=509072eee2c11804287bf807307ed360892053dde89c15ddacd9daa24c63c492963c089d54677598df4422f7d18cbd6a8ebca689841754e8ca44aee1054ddf0c
*/

// this is the full request body
$raw_body = file_get_contents('php://input');

//split value on '='
$digestParts = explode('=', $_SERVER['HTTP_DIGEST']);
$algo = digestParts[0];
$digest = digestParts[1];

// This is known by the client and Rentman only
$token= 'some_secret_key';
$clientGeneratedDigest = hash_hmac($algo, $raw_body, $token, false);

if($digest === $clientGeneratedDigest){
// The webhook call was made by Rentman
}
else{
// The webhook call was not made by Rentman
}

Known limitations

With the current implementation of webhooks, there are two limitations to be aware of:

• Duplicate Webhook Deliveries: In rare cases, multiple webhooks may be delivered for the same event. This is an infrequent occurrence, but is possible.
• Order of Delivery: The order of webhook deliveries might not always reflect the exact sequence of events as they occurred in Rentman. While such instances are uncommon, they can occur.

What do I do if webhook URLs become unresponsive?

If your webhook URL becomes unresponsive, either due to an incorrect setup or issues with your endpoint, Rentman has implemented a notification system to help address the situation.

What do these notifications mean:

These notifications are only visible to crew members with access to the settingsConfiguration module. Ensure that the appropriate crew members in your team have access to this module to stay informed and resolve any issues promptly.

To resolve these issues, you can re-enable webhooks by updating the URL in the Webhooks section in the settings Configuration module, just as you would when enabling webhooks for the first time.