Webhooks

Understanding Hover Webhooks

Webhooks provide a way for Hover to proactively notify your application about important changes to your data in Hover, eliminating the need for you to constantly poll the API. This is particularly useful for knowing when a job has been completed and its measurements are available, when photos have been successfully uploaded, or when a job has encountered a failure.

Think of a webhook as a push notification from Hover to your system. When a specific event occurs (e.g., a job's status changes), Hover sends a POST request to a URL you've configured. This request contains data about the event, allowing your application to react accordingly. This reaction could involve triggering a workflow, updating a database, sending a notification, or simply logging the event.

For example, if a webhook indicates that a job has completed successfully, your system could automatically make subsequent API requests to obtain the measurement data, the measurement PDF, or payment/invoicing information associated with that completed job.

Webhook Verification

For security reasons, newly created webhooks in the Hover API are not immediately active. Before Hover begins sending event notifications, you must verify the webhook.

The verification process works like this:

1. webhook-verification-code Event: When you register a webhook, Hover immediately sends a POST request to the URL you specified. This request includes a webhook-verification-code event, along with a unique code.

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

2. Use the code to verify the webhook: Your application must then make a PUT request to Hover's webhook verification endpoint, including the code from the previous step.

PUT https://hover.to/api/v2/webhooks/{webhook_verification_code}/verify

3. Activation: Once Hover successfully receives this verification request, your webhook is activated, and Hover will begin sending event notifications to the specified URL.

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

Receiving and Handling Webhooks

Once verified, Hover will send POST requests to the URL you provided whenever a relevant event occurs. Each webhook request will include an event attribute that tells you the type of event. The rest of the data within the request will be specific to that event.

To handle webhooks effectively, your application should:

• Parse the event attribute to determine the type of event that occurred.
• Extract the relevant data from the request body based on the event type.
• Process the data as needed (e.g., make another API request, trigger a workflow, send a notification, etc.).

For a comprehensive list of available webhook events and their associated data structures, see the Available Webhooks documentation.