This article will cover how to set up and use a webhook listener for an entity within your instance. Webhook listeners allow you to easily keep track of entities that are created or updated, by sending a JSON representation of them to a specified URL endpoint or email address. For example, you can set up a webhook to monitor new clients that have been created. Please note that the payload received via the webhook follows the same schema and models as the Picksmart APIs.


Locating the webhook listener page

The webhook listener page can typically only be accessed by administrators. Please ask your administrator to adjust your permissions if necessary. If you have the correct permissions, you can access the page under Settings > API > Webhook Listeners in the sidebar.

Adding a new webhook listener

Next, you will be shown all the webhook listeners that have been created for your instance (or your Distribution Channel, in Plan Pro), if any. Click the "New Webhook Listener" button to create a new listener.

On the next page, you will be able to do the following:

  1. Select the entity you want to listen for. For example, clients. Please note that not all entities are allowed, and an invalid entity selection will not activate the webhook.
  2. The function you want to listen for. At the moment, only Create and Update are supported. Selecting a function other than those two will not activate the webhook.
  3. Set up an endpoint. The endpoint you enter in the text field must be a URL on your side that is set up to receive (REST) POST requests. You can then also (optionally) set an authentication type, if your endpoint requires one. If you select an authentication type, you must add a credential of the corresponding type.
  4. If you don't have a URL, you have the option to send the entity to an email address instead. Please ensure that the address you enter is equipped to receive a high volume of emails.

Once the form has been filled out, click the "Save" button. Your new webhook listener will appear in the list. You can edit it at any time to change or enable/disable features.

Conclusion

Now, whenever you create or update your listener's associated entity, it will be sent to your specified endpoint or email address.