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
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
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
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
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
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
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-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
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
}