Webhooks
What are webhooks?
Webhooks are user-defined HTTP callbacks. They are automated messages sent from external systems to PROCESIO when something happens in the external platform. Webhooks have messages (called payload) and are sent to a unique URL in PROCESIO.
Webhooks can be used to receive data from external apps and services when an event occurs. Also, webhooks can be used as triggers for process flows when we want to receive data and use it to kick off a process based on the data received. This allows several different services to connect to PROCESIO and run a process when data is received.
Please keep the webhook URLs private. They can be accessed directly by anyone having the link.
Creating a webhook
PROCESIO webhooks only support POST requests with 'Content-Type': 'application/json'
Go to Webhooks page. By pressing Create webhook, the configuration side panel will open and you will see the following:
1. Webhook Name - this field is mandatory and it has a limit of max length 32 characters.
Webhook names must be unique.
2. Webhook URL - generated by default when opening a new webhook configuration panel, this is the webhook URL that users must provide to the external platform when configuring the webhook there.
To set up your webhook, there are 2 options:
- start listening and send an example data set to the unique URL from third-party services; the data model will be automatically created;
- manually add the payload to generate the data model.
Listening for data
Step 1: Copy the unique webhook URL and paste it in the webhook configuration in the external service/app;
Step 2: Press Start listening. PROCESIO is now listening for the webhook data in order to determine the data structure automatically;
Once you start listening, you will see this page until data is received or until the timer ends, if no data is received.
Step 3: Generate an event in the external service/app that will call the webhook, like updating a record, creating a ticket etc.
Step 4: Once the data is received, you will be able to see the tree structure of the created data model, collapse & expand attributes or search within the structure.
“Listen for another event” will trigger the loading state again. You can generate in the meantime another event from the other platform. If the data structure of the event received is different, the attributes are merged and duplicates removed. The data structure is updated, growing incrementally.
Adding the payload manually
If you choose to manually define the webhook payload, you will see the following screen, where you can add your structure and generate the data model.
The payload structure is taken from the external platform’s webhook documentation.
Editing a webhook
You can edit an existing webhook by selecting the option from the contextual menu, but please be aware that you can only edit the webhook in the same way it was created.
If the webhook was originally created by listening for data, it can only be updated by listening for another event.
If the webhook was originally created by manually adding a payload, it can only be updated by manually manipulating the payload and regenerating the data model.
Deleting a webhook
You can delete an existing webhook by selecting the option from the contextual menu, but please be aware you can only delete a webhook that is not used in a process.
To delete a webhook, please remove it first from any processes that might be using it.
Assigning a webhook
To trigger a process with webhooks, go to Process Designer and select the process to be triggered.
From the top bar, open up the webhooks panel.
You can select one webhook to kick off a process. Once you select a webhook from the dropdown list, it will populate the:
- local variable name
- webhook data model
(Optional) Filter Rules allow you to filter or apply conditions on the data set that will be triggering the process.
Here's an example. Let’s say you have an event “issue updated” that happens in Jira and the payload of a ticket is sent to PROCESIO. If there are no filter rules applied, all event payloads for “issue updated” will trigger your process, no matter what property has changed.
But you may want only payloads with name.old != name.new to be relevant, not all tickets that suffered an update within the Description. By using the complex condition builder, you can build a rule by creating conditions that use the attributes of the data model generated when saving the payload of the event.
You can add unlimited rules and if the conditions are met, the process will be launched.
Unassigning a webhook
To remove a webhook from a process, please open up the "Assign webhook" panel and, from the "Select webhook" field, remove the assigned webhook to clear the input.
