Introduction
A webhook is a short message RentVisie sends to another system the moment something changes, so that system does not have to keep asking. You set up where the messages go on the screen headed Webhooks, with We send a short message to these URLs when data changes. Failed messages are retried up to 5 times. underneath. A New webhook button sits at the top right. Below it is a card headed Endpoints: a table with one row per address you send to, with the columns Description, Webhook URL and Status (Active or Inactive), and a pencil and a bin icon at the end of each row.
You come here when:
- Your fleet-management or planning system needs to know straight away when a vehicle's odometer or fuel reading changes.
- Your website or another tool keeps its own copy of your vehicle classes and has to hear when you change one.
- An integration partner has given you an address to send messages to.
- You want to pause the messages for a while, or check which addresses are still active.
Terms used on this screen
| The screen says | It means |
|---|---|
| Webhook | One address the app sends messages to, with the changes it sends messages about |
| Webhook URL | The web address of the other system, given to you by whoever runs it. It must start with https:// |
| Endpoint | The same as a webhook: one receiving address |
| Events | The kinds of change that trigger a message |
| Asset group | A vehicle class, such as "compact car" or "van 12 m3" |
The screen opens from the Webhooks row on the Integrations screen; see Turn an integration on or off. Use this page when another system should be told about changes as they happen.
How to use
Configuration
There is nothing to switch on first. The Webhooks row on the Integrations screen has no switch; webhooks work as soon as you save one that is Active.
Before you start: the Webhooks screen and the Integrations screen it opens from are for the Company admin role only. You also need the receiving address from whoever runs the other system, and it must start with https://. Ask them as well what they will do with the messages: the app only sends them; it cannot show you whether the other system used them.
Using the Webhooks screen
From the main menu, open Admin → Settings. On the Settings tile screen, click the Integrations tile. In the Bookings & operations card, click Settings on the Webhooks row. The screen headed Webhooks opens.
-
Add a webhook. Click New webhook. A window headed Webhook opens with two parts, Endpoint and Events.
-
Fill in the Endpoint part.
Field Starts as What it does What it accepts Webhook URL Empty, with https:// as a hint Where the messages go A web address starting with https://. Anything else, or an empty box, is refused Description Empty A name so you recognise the webhook in the list, such as "Fleet planner" Any text Active On Turn off to pause sending without deleting the webhook. On or off -
Choose the events. Under Events, Send a webhook when one of these changes is saved., there is a switch for each kind of change. On a new webhook all of them start on. Switch off the ones the other system does not need:
Event A message is sent when Odometer reading An odometer reading is saved for one of your vehicles, by staff, at a handover, or by a tracker Fuel reading A fuel reading is saved for one of your vehicles Asset group One of your vehicle classes is saved -
Click Save. The window closes and the webhook appears in the table with the status Active. If the address does not start with https://, the window stays open with Enter a URL that starts with https:// under Webhook URL. Cancel closes the window without saving anything.
-
Change a webhook. Click its row, or the pencil icon at the end of it. The same window opens with the switches as you left them. Change what you need and click Save.
-
Pause a webhook. Open it, switch Active off and click Save. The status shows Inactive and no messages are sent to it until you switch it on again.
-
Remove a webhook. Click the bin icon at the end of its row. The app asks Delete this webhook?; click Delete to remove it, or Cancel to keep it.
You are done when the row shows the right address and Active.
Key details
What a message holds. Each message is very short. It says what kind of record changed (a vehicle, for odometer and fuel readings, or a vehicle class), which one by its number in RentVisie, which event it was (Odometer reading, Fuel reading or Asset group) and the time in universal time (UTC). It does not carry the reading or the class details themselves; the other system looks those up through its own connection with RentVisie. Give your integration partner this description when they set up the receiving side.
When messages are sent. A message goes out just after the change is saved, to every Active webhook of your company that has that event switched on. A change saved in your company never goes to another company's webhook. Nothing is sent for changes made before the webhook was saved: it is not retroactive.
When the other system does not answer. The app waits up to 10 seconds for an answer. If the other system does not reply, or replies with an error, the app tries again later, first after about a minute and then with longer and longer pauses of up to an hour, up to 5 times. After that the message is dropped. There is no list on this screen of messages that failed; ask your integration partner to check what they received.
A webhook never stops a save. If sending fails, the reading or class is still saved as normal. Staff at the counter see nothing of it.
Saving replaces the events. When you save the window, the app stores exactly the events that are switched on at that moment. Switching an event off and saving stops those messages straight away.
What to do next: tell whoever runs the other system that the webhook is active, and ask them to confirm the first message arrives. The quickest test is to save an odometer reading on a vehicle; see Check and correct a vehicle's odometer and fuel readings.
Q&A
Why does the other system not receive anything, even though the webhook is listed? Check three things on the webhook's row and window: the status says Active, the event you expect is switched on under Events, and the Webhook URL is exactly the address you were given. Then save a change of that kind, such as an odometer reading, and ask the other side whether it arrived. If it still does not, the other system is not answering; the app gives up after 5 tries.
Why does the window stay open with "Enter a URL that starts with https://"? The address is empty or starts with something other than https://, for example http:// or www.. Copy the full address from your integration partner, starting with https://, and click Save again.
Why did the other system get a message I did not expect, after I only changed a vehicle class? Every save of a vehicle class sends an Asset group message, even a save where you only changed its description or a photo. Switch Asset group off on the webhook if the other system does not need it.
Can I see a history of the messages that were sent? No. This screen lists only where messages go. Ask whoever runs the receiving system to check what arrived on their side.
I deleted a webhook by mistake. Can I get it back? No. Click New webhook and enter the address, description and events again.
Can a webhook send booking, customer or invoice changes? Not at the moment. The only events are Odometer reading, Fuel reading and Asset group. Ask RentVisie support if your integration needs other changes.
Why can't I find the Webhooks screen? It is reached from the Integrations screen, which is for the Company admin role only. Ask your company administrator. See Add an employee and set their permissions.
Related pages:
- Turn an integration on or off: the Integrations screen the Webhooks row sits on.
- Check and correct a vehicle's odometer and fuel readings: the readings that trigger the Odometer reading and Fuel reading messages.
- Set up your vehicle classes: the saves that trigger the Asset group message.