What is a webhook?
A webhook (also referred to as web callback or HTTP push API) is a method of sending information from one app to another in real time mode. These notifications occur in response to a particular event (e.g. a code is pushed to a repository or a comment is added to a blog).
Once such event happens, one app makes a request to the URL configured for the webhook. This triggers a different event on the other app. In other words, webhooks help events on one site to invoke behavior on the other site. It is a powerful tool for integrating one app with any other software and creating scripts that will do different jobs.
How do webhooks work in Pics.io?
Pics.io allows you to register webhook URLs for particular events happening in your digital library (e.g. an asset was uploaded, approved or assigned to a teammate).
Every time such event happens, Pics.io creates an Event object. This Event object contains all the relevant and necessary information about this event. After that, Pics.io forwards this Event object to the URL you have defined in the Webhooks settings. This notification is sent via HTTP POST request, and a single event can be sent to more than one webhook endpoints.
How to configure webhook settings?
To configure a webhook, you should do the following:
- open Settings menu
- select My Team section
- open Integrations tab
- click Add webhook to open a form where you can add a new URL for receiving webhooks.
Here you can choose the events that you want to be notified of. There is no limit as to the number of URLs you can create. Just make sure these are dedicated pages on your server that are set up to receive webhook notifications.
Please beware of common mistakes when creating a webhook. One of these mistakes is giving a wrong URL in the webhook settings. Another mistake is not returning a 200 status code from the webhook endpoint.
Receiving and responding to webhooks
All the necessary details of the event are included in POST request and can be used directly, after parsing the JSON body. After the webhook is received at the endpoint, Pics.io should be notified of that. For this purpose, you should make sure that a 2xx HTTP status code is returned back to Pics.io. Pics.io will ignore any other information returned in the request headers or request body.
Testing webhooks before going live
Before you introduce a webhook, it is highly recommended to check if it works properly. One of the ways to do so is to send a dummy test event. Here’s what you should do:
- Go to Settings - My Team - Integrations
- Add the endpoint where you want to send your test events
- Click on the endpoint to see the details
- Сlick send a test webhook button.
Please bear in mind that these are dummy, test events. That’s why they will not direct you back to the real assets, collections, or other events happening in your digital library.
Here’s a list of all the types of events in Pics.io that can be currently sent to a different app with the help of webhooks. Please mind that this list is by no means final. More events are going to be added.