Webhooks - 365 Management

Webhooks - 365 Management

The Webhooks screen allows you to configure integrations that send real-time event notifications from Autocab 365 to external systems.


You can use this to have custom notifications in other applications when an even triggers, for example, sending a notification when a booking is created or updating a system once a booking is complete.


What are webhooks?

A webhook allows one system to automatically notify another system when an event occurs. Instead of your system repeatedly checking for updates, the system sends you a HTTP request containing event data as soon as the event occurs. Webhooks allow you to receive real-time updates about events without needing to repeatedly query the system.


Prerequisites

Before adding a webhook provider, first ensure you have met the following criteria:
  1. A URL where the data will be sent.
  2. Any required API key or authentication details.
  3. Access to the Webhooks section in Management.
  4. Webhook service is enabled under General Settings > Webhooks > Settings.
Info
You may need an administrator to enable the Webhooks permission in the Users > Roles tab.

Accessing the webhooks screen

To access the Webhooks screen:
  1. In Management, navigate to General Settings.
  2. Select Webhooks from the dropdown menu.


Adding a webhook provider

A Webhook provider represents the external system that will receive the event notifications.

To add a provider:
  1. Click Add in the top-right of the screen.
  2. Complete the following fields:

    1. Enabled: Toggle to enable or disable this provider.
    2. Name: Enter the name of the provider.
    3. Provider Base URL: Enter the main URL where the data will be sent (e,g., https://api.mydashboard.com/webhooks/).
    4. API Key Header Name (Optional): Enter the authorisation header name to be sent along with the secret key or unique ID.
    5. API Key: Sent with the API Key Header Name, this can be a unique ID/GUID or secret key provided by the webhook service.
    6. Description: Enter a short description of the provider.

Now, you can create a Webhook.


Creating a webhook

A Webhook represents the event which triggers a notification.
  1. On the same modal screen, click Add Webhook.
  2. Complete the following fields:

    1. Enabled: Toggle to enable or disable this webhook.
    2. Name: Enter a unique name for the webhook.
    3. Description: Enter a short description of the webhooks purpose.
      Event URL Suffix:  Enter the suffix at the end of the provider URL.
    4. Event Type: Use the dropdown menu to select the type of system event that will trigger the webhook.
    5. Event Filter Recipe (Optional): Select a booking recipe to use as additional filtering logic when the webhook is triggered.

  3. Click Create to add the Webhook and then again to add the Provider to your system.
After you have configured the webhook provider and webhook, you can then receive notifications when an event is triggered.

What events can you subscribe to?

When creating a webhook, you can choose which event will trigger it. Below is a list of available events with names and descriptions:
Booking Created
Triggered when a booking is created in the Autocab system.
Booking Dispatched
Triggered when a vehicle is dispatched for a booking.
Booking Arrived
Triggered when the driver signals that they have arrived at the pickup location.
Booking POB (Passenger On Board)
Triggered when the driver signals that the passenger is on board the vehicle.
Booking Complete
Triggered when the driver signals that the trip is completed.
Booking Cancelled
Triggered when an existing booking is cancelled by a user.
Booking No Fare
Triggered when a booking is flagged as a no fare.
Booking Recovered
Triggered when a booking is returned from a vehicle/driver by an operator.
Vehicle Position Changed
Triggered for vehicle position changes while on a booking
Vehicle Data Changed
Triggered when vehicle details are updated (e.g. make, model, colour)
Invoice Created
Triggered when a customer invoice is created within the accounts section.
Driver Paid In Out
Triggered when a driver transaction is processed.
Driver Shift Started Ended
Triggered when a driver starts or ends a shift in the system.


How a webhook works

When you create a webhook, you are telling Autocab 365:
  1. What event to listen for (e.g. Booking Created)
  2. Where to send the data (your webhook URL)
  3. How to authenticate the request (API key/header)
When an event occurs (e.g. a booking is created), Autocab 365 sends a POST Request to your URL.

The final URL that receives the data is created by combining two fields:

Provider Base URL + Event URL Suffix

For example:

The request sent to your system includes the settings configured in the steps above:

{ "name": "ExampleBookingCreatedWebhook", "callbackUrl": "https://api.mydashboard.com/webhooks/booking-created", "authentication": { "headerName": "Authorisation", "headerValue": "Bearer <secret-api-key>" } }

Also sent in the same request is a JSON payload containing the event data. (The exact data will vary depending on the event you selected.)

For example, the JSON payload sent for a 'Booking Created' event can consist of the following:
Booking Created - Example Payload:
{ "EventType": "BookingCreated", "BookingType": "Active", "TypeOfBooking": "ASAP", "Id": 6932, "OriginalBookingId": 6932, "Pickup": { "Type": "Pickup", "Address": "Autocab, Circle Square, Circle Square, Manchester M1 7FS, UK", "Zone": { "Id": 664, "Descriptor": "Man City", "Name": "City Manchester" }, "Coordinates": { "Longitude": -2.2389369444444442, "Latitude": 53.47267194444444 } }, "Vias": [], "Destination": { "Type": "Destination", "Address": "Manchester Airport (MAN), Manchester Airport, Manchester Airport (MAN), Manchester M90 1QX, UK", "Zone": { "Id": 694, "Descriptor": "Knutsford", "Name": "Knutsford" }, "Coordinates": { "Longitude": -2.2771619444444444, "Latitude": 53.355356944444445 } }, "PickupDueTime": "2025-01-07T12:27:00.2252455", "DropOffDueTime": null, "Company": { "Id": 1, "Name": "Company 1", "RegisteredNumber": "", "CompanyCode": "" }, "Account": null, "LoyaltyCardID": null, "LoyaltyCardCostValue": 0, "AccountType": null, "PaymentType": "Cash", "Name": "Mr Henry ", "TelephoneNumber": "", "CustomerEmail": "", "Capabilities": null, "Priority": 0, "Passengers": 0, "Luggage": 0, "DriverNote": "", "OfficeNote": "", "YourReferences": { "YourReference1": "", "YourReference2": "", "YourReference3": "", "YourReference4": "", "YourReference5": "", "YourReference6": "", "YourReference7": "", "YourReference8": "" }, "OurReference": "", "FlightDetails": "", "Pricing": { "Fare": 0, "Cost": 17, "Price": 17, "ExtraCost": 0, "FixedCost": null, "FixedPrice": null, "ChargingAreaCost": 0, "ChargingAreaPrice": 0, "WaitingTime": 0, "WaitingTimeChargeable": 0, "GratuityAmount": 0, "CostSource": "Variable Price: Day Rate passenger", "PricingTariff": "Day Rate passegner", "PromotionCodeDiscount": { "LoyaltyCardId": -9223372036854776000, "BookedDiscount": 0, "FinalDiscount": 0, "PayDriver": false, "RoundUpToNearest": 0, "Timestamp": "0001-01-01T00:00:00" }, "PricingSource": "Variable" }, "PriceComparison": { "GpsMeterDistance": 0, "GpsMeterPrice": 0, "GpsMeterPriceSource": "", "SystemEstimatedDistance": 10.3, "SystemEstimatedPrice": 17, "SystemEstimatedPriceSource": "Variable Price: Day Rate passenger", "EstimatedTime": "00:29:46.8310000" }, "Distance": 10.3, "SystemDistance": 10.3, "MeterDistance": 0, "MeterDistanceAsMetres": 0, "BookingSource": "OperatorWeb", "BookedAtTime": "2025-01-07T12:27:00.2565303", "BookedBy": "autocab", "CabExchangeAgentBookingRef": "" }

Once your system receives the webhook, it can use the data to automatically perform actions. For example, your system could trigger notifications or alerts.


Troubleshooting tips

Webhooks are sent instantly when events happen, so your system must be able to receive and process the request, otherwise errors may occur. 

If your webhook is not working as expected, use the list below to help identify and fix the issue:
System not receiving any data
If your system is not receiving any webhook requests, there may be a few possible causes:
  1. Webhook is disabled - Ensure that both the provider and webhook are enabled in 365.
  2. Check your webhook source - Make sure that your webhook provider's system is working and able to accept requests
  3. Incorrect URL - Double-check the Provider Base URL and Event URL Suffix.
  4. Wrong event selected/Event not triggered - Confirm you have chosen the correct event type and check to see if the selected event has actually occurred.
Incorrect or invalid URL (404 Errors)
If you're encountering 404 errors, your webhook URL could not be reached.

To rectify this, ensure that your URL is correct, accessible, and not blocked by a firewall.
Authentication errors (401 / 403 Errors)
If you are encountering 401 or 403 errors, your system is refusing the connection due to invalid authorisation.

Check that your credentials (API key and header name) are correct.
Connection issues (Request times out)
If your webhook is failing, it may be because your system is too slow or unreachable:
  1. Offline server - Make your system is online.
  2. Slow response time - Your system should respond quickly, otherwise the sending system (Autocab 365) may assume the delivery has failed and the request times out.
  3. Firewall or network blocking requests - Ensure your system allows for incoming requests.