Tech Blog

Webhooks: Receiving Alerts and Data Insights

Dec 06, 2022

By Matt Myers, Senior Back-end Engineer

What is a webhook?

A webhook is a way for two systems to communicate over an HTTP interface. It allows the system that is the source of the data or events to integrate programmatically with the subscriber or client system. At a high level, it allows one system to notify another (e.g., client system) that an event has occurred. In our case, we use webhooks to alert our clients that their image or group of images has completed processing and provide the clients with the data that we’ve pulled from the images in real time.

Introduction

Running hundreds or thousands of images simultaneously through dozens of AI models can take more time and generate more data than a single synchronous HTTP call can reasonably support. To prevent FoxyAI’s customers’ servers from idly waiting, or actively polling our API, we’ve created an asynchronous approach using webhooks. The second the data is ready for our customers to consume, our event-driven system will send it directly to the customer’s API using webhooks—enabling our customers to utilize and immediately benefit from all the insights our state-of-the-art AI models can detect.

Why use webhooks?

  1. Save on resources vs. integration methods like polling.

    With long-running requests, where there can be hundreds or thousands of images, the system might take longer than a handful of milliseconds. Your servers have worked hard enough already; allow them to rest and wait for our system to alert you that the data is ready!
  2. Real-time updates and syncing data with ease.

    Any time an image group or image is updated, we’ll immediately send the data to the webhook supplied in the original create request—meaning your data will always be in sync with our data, even when images or models are added.
  3. Handle updates at your own speed.

    By placing a queueing system of your choice in unison with your webhook endpoint, you can batch images or limit the speed at which you process images, allowing you to fine-tune how you use your resources
  4. Create Resiliency.

    We’ll retry sending the request to your webhook until you accept it or we determine that the server is too unhealthy to receive requests. Pair your webhook endpoint with a queueing system to ensure that you can retry your database updates in the event your database or server is overwhelmed.
  5. Stateless.

    By providing a unique webhook URL to the image, or by using the metadata fields, you can supply all the information your server would need to look up and update your records with our AI insights.

It’s worth noting that webhooks aren’t a one size fits all solution  Some applications won’t have the ability to receive HTTP requests (example: a pure frontend application) without their own paired backend service—meaning they’ll have to integrate by polling our API to retrieve the data.

Integrating with webhooks

It’s a straightforward process with just two easy steps!

  1. Stand up your own endpoint to handle POST requests.

    For the purposes of a quick test, we’ll use https://webhook.site/, so we don’t have to create our own servers. Once you navigate the site, you should receive your unique URL under the “Your Unique URL” row. Copy that URL for the next step. The format of the data being sent to the webhook can be found in our documentation
  2. Create an image or image group and supply it as the field “webhookUrl”.

    Image groups allow you to group images together. It also allows for the computation of accurate overall property condition and property quality of the images through our proprietary algorithm. But for the sake of simplicity, we’ll just be creating a single image.

    Here’s the curl request we used:

    curl –location –request POST ‘https://api.foxyai.com/image’ \
    –header ‘Authorization: Bearer Your_API_key’ \
    –header ‘Content-Type: application/json’ \
    –data-raw ‘{
    “url”:”https://images.unsplash.com/photo-1556911220-bff31c812dba?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxzZWFyY2h8Mnx8a2l0Y2hlbnxlbnwwfHwwfHw%3D&w=1000&q=80″,
    “models”: [“object_detection”],
    “webhookUrl”: “https://webhook.site/14238d9b-2be3-4e5b-875a-9790446091e2”

    }’

    NOTE: Make sure to replace “Your_API_key” with the API key for your org/application!

And the request was a success! Now the ML model “object_detection” is running behind the scenes to analyze the image.

Navigating back to https://webhook.site/, we can see that the data was posted out from the FoxyAI system to the defined “webhookUrl” in the image creation. The data includes the location and confidence of the Cabinets, Microwave, Stove, and other objects and features the model detected in the image.

We are really excited about the impact that using webhooks has had on our customers’ experience—allowing them to utilize and immediately realize all the insights the FoxyAI state-of-the-art AI models can detect!