Webhooks

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.

Job State Changes

`job-state-changed`

When a job's state changes, you will receive a webhook with the following post body.

{  
  "event": "job-state-changed",  
  "webhook_id": 230293,  
  "job_external_identifier": "order01239181",  
  "job_id": 19402492,  
  "state": "processing_upload",  
  "content-available": 1,  
  "job_estimated_hours_to_completion": 1.3902
}

The state attribute lets you know which state the job just entered. Hover currently provides the following job states for job-state-changed events:

State	Description
`uploading`	Waiting for the contractor or homeowner to take pictures of the home and submit them.
`processing_upload`	The uploaded data has been received and we're verifying the uploaded data and authorizing the uploaded user.
`submitting`	The uploaded data is being submitted to our processing pipeline.
`working`	We're turning the 2D images you uploaded into a photo realistic 3D model and measurements.
`waitlisted`	Your account is on our waitlist. The job will stay in this state until we take your account of the waitlist.
`waiting_approval`	The user that uploaded this job must get approval from their org's administrator before the job will progress.
`retrieving`	3D model and measurements are ready. When the job is in this state we're fetching the results from our processing pipeline.
`processing`	Apply partner specific branding and other final processing
`paying`	We're collecting payment for the job
`complete`	All done. Your results are paid for and available.
`failed`	We weren't able to finish processing this job.
`cancelled`	This job was cancelled before we finished processing it.
`requesting_corrections`	The client was unhappy with the job and we're sending it back to the processing pipeline for corrections.
`processing_upload_for_improvements`	More images were uploaded for the job after processing was done. Let's pre-process those images and get them ready for the pipeline.
`requesting_improvements`	We've received and processed an upload for an already complete or failed job. In this state we're sending the job back to the processing pipeline for improvements.

Inspection Checklists

`inspection-checklist-created`

When an inspection checklist has been created, you'll receive a webhook with the following post body:

{  
  "event": "inspection-checklist-created",  
  "inspection_checklist_id": 573,  
  "job_id": 333  
}

`inspection-checklist-updated`

When an inspection checklist has been updated, you'll receive a webhook with the following post body:

{  
  "event": "inspection-checklist-updated",  
  "inspection_checklist_id": 573,  
  "job_id": 333  
}

Capture Request State Changes

`capture-request-state-changed`

After creating a capture request, you will receive webhooks letting you know about it's state changes. Here's an example:

{  
  "capture_request_id": 4290429,  
  "state": "complete",  
  "event": "capture-request-state-changed",  
  "job_estimated_hours_to_completion": 0.0,  
  "job_client_identifier": "test-client-identifier-992759",  
  "job_id": 19402492,  
  "job_external_identifier": "order01239181"  
}

Hover currently provides the following job states for capture-request-state-changed events:

State	Description
`new`	The request is new and the homeowner hasn't connected yet.
`connected`	The capture request has been associated with a user record belonging to the homeowner.
`completed`	The job has been captured.
`deleted`	The request was deleted before the job was captured.

Deliverable Changes

`deliverable-change-request-state-changed`

When a deliverable change request's state changes you'll receive a webhook with the following body:

{  
  "event": "deliverable-change-request-state-changed",  
  "webhook_id": 230293,  
  "job_id": 19402492,  
  "state": "complete",  
  "deliverable_change_request_id": 3234  
}

Hover currently provides the following job states for deliverable-change-request-state-changed events:

State	Description
`first_attempt`	We're still making our first attempt to upgrade this job's deliverable
`waiting_for_job_to_finish`	The job wasn't in a state that allowed a deliverable upgrade. In this state we wait for the job to be finished so that we can request the upgrade afterward.
`second_attempt`	We weren't able to upgrade the job's deliverable the first time, so we waited for it to finish. In this state we make our second and final attempt to upgrade the job's deliverable.
`complete`	The upgrade was completed and the user will get the new requested deliverable
`failed`	We weren't able to upgrade this job.

Estimate Groups

When an estimate is created, you will receive a webhook event with the following payload, noted by the complete state:

`estimation-estimate-group-state-changed`

{
  "estimation_estimate_group_id": "e10191d5-5dd6-4821-b3a1-255b6f94147c",
  "state": "complete",
  "event": "estimation-estimate-group-state-changed",
  "webhook_id": 423
}

`estimation-estimate-group-updated`

This trigger fires when an estimate group is updated, which includes any of these following events:

The estimate group is updated
A line item from the estimate group is updated
A discount for the estimate group is created/updated/deleted

{
  "estimation_estimate_group_id": "e10191d5-5dd6-4821-b3a1-255b6f94147c",
  "job_id": 1234,
  "event": "estimation-estimate-group-updated",
  "webhook_id": 423
}