Skip to main content

Use incoming webhooks to get real-time updates

Listen for events on your HopDrive account so your integration can automatically trigger reactions.​

HopDrive uses webhooks to notify your application when the status changes on an active move. Webhooks are particularly useful for asynchronous events like when a vehicle is delivered successfully, a cancelation request is processed, or just to be alerted as the vehicle moves.

Requests made to this endpoint require an authorization header using your authentication token:

How HopDrive uses webhooks​

A webhook enables HopDrive to push real-time notifications to your app. HopDrive uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Steps to receive webhooks​

You can start receiving event notifications in your app using the steps in this section:

1) Identify the events you want to monitor and the event payloads to parse. 2) Create a webhook endpoint as an HTTP endpoint (URL) on your local server. 3) Handle requests from HopDrive by parsing each event object and returning 2xx response status codes. 4) Test that your webhook endpoint is working properly by passing a sample payload. 5) Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL. 6) Register your publicly accessible HTTPS URL in the HopDrive /webhooks endpoint with a POST.

How to create a webhook endpoint​

Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTP or HTTPS endpoint on your server with a URL. If you’re still developing your endpoint on your local machine, it can be HTTP. After it’s publicly accessible, it must be HTTPS. You can use one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

Step 1: Identify the events to monitor​

Use the API reference guide to identify the HopDrive events and their event objects your webhook endpoint needs to parse.

Step 2: Create a webhook endpoint​

Set up an HTTP endpoint on your local machine that can accept unauthenticated webhook requests with a POST method.

Step 3: Handle requests from HopDrive​

Your endpoint must be configured to read event objects for the type of event notifications you want to receive. HopDrive sends events to your webhook endpoint as part of a POST request with a JSON payload.

Check event objects​

Each event is structured as an event object with a type, id, and related HopDrive resource nested under data. Your endpoint must check the event type and parse the payload of each event.

Event Payload
{
  "id": "eaf49bb0-22a9-11ed-a39b-53807037c73c",
  "object": "event",
  "version": "1.0.0",
  "data": {...}
}

Return a 2xx response​

Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating the BOL record in your system.

Built-in retries​

HopDrive webhooks have built-in retry methods for 3xx, 4xx, or 5xx response status codes. If HopDrive doesn’t receive a 2xx response status code for an event after 3 tries, we mark the event as failed and stop trying to send it to your endpoint.

Use webhook signatures to verify that HopDrive generated a webhook request and that it didn’t come from a server acting like HopDrive.