Setting up and verifying webhooks

Webhooks let vehReports tell your own systems about events the moment they happen — a report signed off, an agreement closed, a licence check flagged — so your software doesn't have to keep polling the API to find out. This guide covers adding an endpoint and choosing events, verifying that each delivery genuinely came from vehReports, and using the deliveries log to keep your integration healthy.

#What webhooks are for

A webhook is a small message vehReports sends to a URL you control whenever something you care about happens. Instead of your software repeatedly asking "has anything changed?", vehReports pushes the event to you as soon as it occurs.

Typical uses:

• Posting "report signed off" into a fleet or job-management system so a vehicle is marked ready.
• Alerting your team in chat when an inbound inspection comes back with a flagged verdict.
• Updating a hire-desk system the instant a rental agreement is signed or closed.
• Kicking off a follow-up when a driver licence check returns points or a failure.
• Watching your credit balance so you can top up before sign-off is blocked.

Webhooks are part of the API feature set. They cost nothing to set up or receive — there are no per-delivery charges. The only two actions that ever use a credit anywhere in vehReports are signing off an inspection report and signing a rental agreement; receiving a webhook about those events is free. For the wider integration picture, see Using the vehReports API.

#Before you start

You will need:

• API access switched on for your company. Webhooks live under the API area alongside your API key and base URL. If you can't see the API area, ask an Owner to switch it on.
• A publicly reachable HTTPS URL on your side that can receive a POST request and respond quickly. This is your "endpoint".
• The ability to read the raw request body and a request header in whatever language your endpoint is built in — that's all you need to verify a delivery.

You don't need to write any vehReports-side code. Adding an endpoint and choosing events is all done on screen.

#Adding an endpoint

In the API area, open Webhooks and add a new endpoint:

1. Enter the endpoint URL — the address on your side that should receive events. Use an HTTPS URL so the payload and signature can't be read in transit.
2. Choose which events it listens for — tick the events you want this endpoint to receive (see the full list below). An endpoint only ever receives events it's subscribed to, so you can keep different endpoints for different jobs (for example, one for inspections, one for billing).
3. Save the endpoint. It has a signing secret you'll use to verify deliveries (covered further down).
4. The endpoint starts active. You can switch it between active and paused at any time.

#Active vs paused

• Active — vehReports sends matching events to the endpoint.
• Paused — the endpoint stays configured (URL, events and signing secret are kept) but no events are sent. Pause an endpoint while you do maintenance on your side, then re-activate it when you're ready. Note that events that fire while an endpoint is paused are not queued up and replayed later.

#Running more than one endpoint

You can add several endpoints. The same event can go to more than one endpoint if more than one is subscribed to it — handy when, say, your operations system and a separate monitoring tool both need to know about flagged verdicts.

#Events you can subscribe to

When you set an endpoint up you'll see the current list of events. They span the areas you'd expect:

Inspections & reports

• report.completed — an inspection report has been signed off and locked
• inspection.verdict_flagged — an inspection verdict was flagged (for example, concerns)

Rental agreements

• agreement.signed — a rental agreement has been signed
• agreement.return_due — a rental return is due soon
• agreement.closed — a rental agreement has been closed

Driver licence checks

• licence.checked — a driver licence check was run
• licence.failed — a driver licence check failed
• licence.points_flagged — points were flagged on a licence check

Vehicles & customers

• vehicle.created — a vehicle was added
• vehicle.updated — a vehicle was updated
• customer.created — a customer was added

Billing & credits

• credits.purchased — credits were purchased
• credits.low — the credit balance is running low
• credits.expiring — credits are expiring soon
• payment.succeeded — a payment succeeded
• payment.failed — a payment failed
• subscription.cancelled — a subscription was cancelled

You can change an endpoint's subscribed events at any time — tick or untick events and save. The change takes effect for events that fire after you save.

#A note on what triggers each event

These events mirror what happens in the app. report.completed and agreement.signed correspond to the moments a credit is spent (sign-off and signing). inspection.verdict_flagged only fires when a template's verdict rules apply — for example new damage over a threshold, or a refuel required on an inbound report. The credits.low and credits.expiring events are useful early warnings: remember that running out of credits never stops you building drafts, running licence checks or adding records — it only blocks sign-off until you top up.

#Verifying a delivery is genuinely from vehReports

Because your endpoint URL could in theory be hit by anyone who learns it, you should verify every delivery before you act on it. vehReports signs each delivery so you can confirm it's authentic and hasn't been tampered with.

#How the signature works

Every delivery includes a signature header containing an HMAC-SHA256 signature of the message body, computed using your endpoint's signing secret. Because only you and vehReports know that secret, a valid signature proves the event came from vehReports and that the body wasn't altered on the way.

#Verifying the signature on your side

1. When a request arrives, take the raw request body exactly as received — do not parse and re-serialise it first.
2. Compute an HMAC-SHA256 over that raw body using your endpoint's signing secret as the key.
3. Compare your computed value with the value in the signature header. Use a constant-time comparison if your language offers one.
4. If they match, the event is genuine — process it. If they don't match, reject the request (return an error and ignore the payload).

#Where to find the signing secret

The signing secret is available in the endpoint's settings in the Webhooks area. Treat it like a password: store it securely on your side and don't expose it in client-side code or logs.

#Why this matters

Verifying the signature means you only act on events that really came from vehReports, never on spoofed requests that someone has fired at your URL. It's the difference between a webhook URL being a convenience and being a liability.

#The deliveries log

Each endpoint keeps its own log of what it has sent, so you can see at a glance whether your integration is healthy.

Open an endpoint to see its recent deliveries. For each one the log shows:

• Which event fired (for example agreement.signed).
• When it was dispatched — the time vehReports sent it.
• The outcome — whether your endpoint accepted it (delivered), failed, or is still pending.
• How many attempts it took.

#Diagnosing failed deliveries

When a delivery fails, the log shows the outcome so you can see what happened. Common culprits:

• Timeouts — your endpoint took too long to respond. Acknowledge the request quickly (return a success response) and do any heavy processing afterwards, rather than making vehReports wait.
• Rejected signature / 4xx response — your endpoint returned an error, often because signature verification failed. Re-check that you're signing the raw body with the correct secret.
• Server errors / 5xx — something broke on your side while handling the event.

#Filtering the log

You can filter the deliveries log by outcome (delivered, failed, pending) and by date, so you can focus on a specific window — for example, just the failures from the afternoon you changed your endpoint — rather than scrolling the whole history.

#Tips and good practice

• Always verify the signature before acting on a payload — it's the single most important step.
• Respond fast, then process. Return a success response immediately and do the real work (database writes, notifications) afterwards, so you don't trip timeouts.
• Be idempotent. If a delivery is retried, your endpoint may receive the same event more than once. Make sure handling the same event twice doesn't cause duplicate records or actions on your side.
• Use HTTPS so the payload and signature are protected in transit.
• Keep separate endpoints for separate concerns if it helps you reason about them — for instance, billing events to one URL, operational events to another.
• Pause rather than delete while you're doing maintenance, so the URL, events and signing secret are preserved.

#Common questions and "what if"

Do webhooks cost credits? No. Setting up endpoints and receiving deliveries is free and unlimited. Only signing off an inspection report and signing a rental agreement use a credit.

My endpoint is rejecting valid events — what should I check? The usual cause is computing the signature over a reformatted version of the body. Make sure you're computing the signature over the raw request body exactly as received, and that you're using the correct signing secret for that endpoint. Reformatting or re-serialising the JSON before checking will always produce a mismatch.

An event didn't arrive — where do I look first? Open the endpoint's deliveries log. If the event is there with a failed outcome, the outcome and attempt count will tell you what happened on your side. If it isn't there at all, check the endpoint is active (not paused) and that it's subscribed to that event.

Will I get events that fired while my endpoint was paused? No — events that fire while an endpoint is paused are not sent. Re-activate the endpoint to start receiving new events again.

Can I change which events an endpoint listens for later? Yes. Edit the endpoint, tick or untick events, and save. The change applies to events that fire after you save.

Can the same event go to two systems? Yes — add two endpoints and subscribe both to that event.

Do I need a separate signing secret per endpoint? Each endpoint has its own signing secret. Verify each endpoint's deliveries with that endpoint's secret.

#Related help

• Using the vehReports API — the API key, base URL, available endpoints, and which calls are free.
• Understanding credits — what's paid and what's free — what triggers the only two credit-using actions you'll receive events about.
• Signing off, sending and managing a report — the moment a report.completed event fires.
• The rental lifecycle: handover, return and close — the points where agreement events fire.