Public API Webhooks are a service that enables you to receive notifications about changes in your account, eliminating the need for constant polling through the Rentman Public API.

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.

Note: Using webhooks requires technical programming skills and experience. If you lack these skills, we recommend seeking assistance from an external developer or company. Please note that our Support team is not trained in this field and cannot provide assistance with webhook implementation.

Setting up Public API Webhooks

  1. To enable webhooks, go to the Screenshot 2023-11-23 at 15.56.05.png Configuration module and select "Extensions"
  2. Scroll down to Webhooks section and click “Connect”image-20231120-112332.png
  3. This pop-up will appear:image-20231120-112310.pngHere 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"
}
More complex items, like Subprojects or planned equipment groups, can have more extensive messages structures, that would include pointers to parent items too.
{
"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"
}
When an item is deleted, the message contains slightly different details in its items section:
{
"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"
}

The payload will always contain these components:

  • account - account name the message is originating from
  • user - id and Public API reference to the employee that initiated the change. Can be null for actions not performed by users, such as when a document is digitally signed
  • eventType - create, update or delete
  • itemType - type of the item, that was created, updated or deleted. Possible item types are:
Possible itemTypes
  • Appointment, AppointmentCrew, Accessory, StockLocation, CrewAvailability, InvoiceLine, Contact, Contract, ProjectCost, SerialNumber, Factuur, File, Folder, ProjectFunction, ProjectFunctionGroup, TimeRegistrationActivity, Ledger, Subrental, SubrentalEquipmentGroup, SubrentalEquipment, Equipment, ProjectEquipmentGroup, Crew, Quotation, ContactPerson, ProjectCrew, ProjectVehicle, ProjectEquipment, Project, ProjectRequest, ProjectRequestEquipment, CrewRate, CrewRateFactor, Reapair, WarehouseScan, WarehouseScanner, EquipmentSetContent, Status, Subproject, TaxClass, ProjectType, TimeRegistartion, Vehicle, StockMovement

Rentman Tip: You can append the “ref” value to easily query the user who triggered the webhook, by simply appending it after the base API url https://api.rentman.net. Likewise, you can do the same with the “ref” value of each item in the payload.

  • items - For creates and updates, message contains array of object, where each object represents one created/updated item. The object contains ID of the item, Public API reference and also nested object of the same structure, pointing to the parent, if one exists. If there’s no parent, value of parent is equal to null. For deletes, items is an array of integers, containing IDs of items, that were deleted
  • eventDate - date and time, when event has happened

Validating the authenticity of the webhook payload

/* 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
}
Was this article helpful?
0 out of 0 found this helpful

Articles in this section