Webhooks

With V7's workflow logic, you can already design simple or very sophisticated automation for your annotation pipeline. However, if you want to go one step further and include custom automation using no-code solutions like Zapier and developer solutions like AWS Object Lambda, you can include one specific stage into your workflow - the Webhook stage. But first, what are Webhooks?

Webhooks are a way for applications to communicate with each other in real-time. One way of communication is that App 2 asks App 1 for some data, and App 1 sends the data if it happens to have what App 2 wants.

Webhooks, on the other hand, are automated messages sent from apps when something happens.

Those messages or “payloads” can be anything that the receiving end (or App) is expecting and knows how to work with. In this case, App 1 simply needs to know where to send the message, or in other words - it needs to know a unique URL. Once the payload reaches the receiving app, it can do whatever it wants with it, like sending you a notification or doing some computation with the information provided.

In the case of the V7 Webhook stage, every time an image or item reaches that stage, It sends out a message to the specified URL where the payload is then processed. When adding a Webhook stage, you will of course need to provide this URL - and if your app needs some sort of authorization, you can add that right here and it will be included in the header of the message.

The most important decision you need to make at this point is to include the annotation data or not. If you don't, the payload will simply include the metadata of the image. If you include the annotation data, the message that is sent out will then look similar to this one right here. It includes data following the standard Darwin JSON annotation format.

For a detailed overview of this format, feel free to have a look at the full video that describes it or at the documentation. Links are in the description.

Now, with all this information, you can very easily access the data you need for your custom logic. The payload includes metadata of the item, and, as mentioned, if selected, the annotation data including information on the annotators, tags, and more.

For instance, here have a line annotation, with the label Traffic Boundary Line, created by Kevin Chang. We then also have a bounding box for a vehicle. Using the Webhook stage that sends out this information, you can, for example, easily use Zapier to search for certain tags or write custom functions in AWS Object Lambda to do more complex computations.

Let's have one more detailed look at how the data would flow through a workflow. Let's start by creating a new workflow. Now, with this simple workflow, let's go ahead and add our Webhook stage. To connect the Webhook stage to our workflow, let's go ahead and connect that first to our annotation stage, and then to our review stage.

Let's also go ahead and connect the failed output to the review stage because, in the end, it's still better to forward your item to the next stage, even after a failed attempt of sending yourself a Slack notification using Zapier for example, than moving it back one stage.

Okay, let's go ahead and finish our Webhook setup. We need to connect our URL, as already discussed, and in this case, I'll be using the Webhook site for this little demo. In your case, if you need authorization, you can here add your key for that.

Okay, so let's have a brief look at how the data would flow through this workflow. In the beginning, we have our data in this dataset stage, if we had connected a dataset.

If we then proceed to the next stage, our data or images, for example, would go into the annotation stage. We here can add labels and tags, and once we proceed into the next stage, our images will come to the Webhook stage. Here, our images will automatically be sent to the URL that we have provided. On the receiving end, our app would execute our custom logic and we would be happy.

After our app has successfully, or in this case, also unsuccessfully, processed our message it will be forwarded to the review stage.

Now to see if our webhooks page works correctly with the URL that we've provided, you can actually use this test button right here, which is very useful to see if it works. So if we click this button here, we can see that we have executed a test for the Webhook stage, and that it has passed successfully.

Okay, continuing, we would now be in the review stage. Here, we have some reviewers who can then accept all annotations, which will then proceed the items to the complete stage, or they can reject the annotations, which would then forward the items back to the annotation stage.

One would reject some annotations if they are poorly done, or if there are some annotations missing.

Once the items are back in the annotation stage, annotators can redo the annotations or add missing annotations, and forward them back to the webhook stage, allowing the loop to continue until all items have passed successfully and are accepted.

With those Webhooks, you can implement any logic that you need for your specific case.

For example, let's say you want to compute the area of an annotation or just count the number of pixels. You can then write a custom function in AWS Object Lambda that then adds a tag to the image, for example, requires specific review by specific people, for example, or you can just send a Slack message using Zapier.

Let's say during the annotation stage, an annotator has added a tag stating “urgent” or “difficult”. This is then forwarded to the Webhook stage and, using Zapier, you can filter through tags, and if those tags exist on an image you then again get a Slack notification.

One more example could be that you want to count the number of annotations or labels.

Let's say you have a specific product that has at least 10 screws but there are only 8 annotations. You can then just have your custom function in AWS Object Lambda that just adds a tag “missing annotations”.

You can see that Webhooks are a very versatile, yet simple and easy-to-integrate concept that can be very powerful.

That was it. I hope this video helped you with getting started with V7.