Leveraging Webhooks with Hover

Introduction

Webhooks are used to notify your application when your jobs have changed state. This is commonly used to know when a Hover job is complete and its measurements are available. Additionally, you can know when photos have been successfully uploaded, or if a job has failed.

Why would I use a Webhook?

A webhook is a way to get a status update from a service. This status update might trigger an event in your system, or just be used for logging purposes. For example, a Webhook indicating job status might return a "Failed" state, in this case you may have an event that triggers to retry the job, or re-queue the job for a field technicians to complete. The way you leverage a webhook is nearly limitless, but it's a way to ask once for Hover to send you status updates about something whenever they happen (we push information to you, rather than you having to pull it everytime you want).

Webhook Verification

When creating a webhook on the Hover API, it is not functional or active until the webhook has been verified. The verification process involves sending a request to the URL specified when creating the webhook. This request will include the code needed to verify the webhook. You then make a POST request to the webhook verification endpoint with the code provided, one a webhook has been verified and Hover will begin posting status updates.

If there is an issue sending a webhook, the response from your server will be saved in the last_error attribute in the webhook body.

webhook-verification-code

When you create a webhook, we immediately send a request with the webhook-verification-code event. You will need to use the included code to verify your webhook and activate it.

{  
  "event": "webhook-verification-code",  
  "webhook_id": 230293,  
  "code": "03947FE2-28C3-4EB1-AD44-B4258B3345BB"  
}

Receiving Webhooks

When you create a webhook you'll specify a URL. For each event that we send webhook notifications for we'll make a POST request to that URL. Each webhook request will include an "event" attribute that let's you know what type of even it's for. The rest of the data included is specific to the event.

To see a list of Available Webhooks, click here.