Licenses | | Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
, | Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
, | Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
|
Since | | Status |
|---|
| colour | Green |
|---|
| title | VERSION 6.0 |
|---|
|
|
Quick guide
Create a new incoming webhook endpoint by using the command webhook.put.
Set the eventKey to the name of an event to be fired internally every time after this webhook has been received.
Remember the url or uuid of the webhook (is returned after it was created).
Create a pipeline which listens for the eventKey fired by the webhook using the event.listen command and store it to the property store. This pipeline will be executed every time this webhook is called.
To call a webhook from outside use the command webhook.receive and the webhook uuid, example:
https://hub-<NS>.pipeforce.net/api/v3/command/webhook.receive?uuid=<uuid>
To trigger a webhook from inside a pipeline to an external system, use the command webhook.send.
Introduction
A webhook is a unique url pointing from outside to PIPEFORCE. When called, produces an internal event message which in turn can be consumed by a pipeline using the command event.listen.
| Info |
|---|
Note: If an url in this article contains <NS>, replace it by the namespace of your PIPE|FORCE instance. |
Incoming webhook
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
Replace <NS> by your namespace.
Replace <uuid> by the UUID of your webhook.
Setup incoming webhook via CLI
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
| Note |
|---|
Since a webhook is secured by its uuid which is a secret and hard to detect, make sure the webhookUrl is kept secure between the two systems. Note: PIPEFORCE scans regularly the internet for this secret and if it finds it, the according webhooks will be deactivated for security reasons. So never make it public available! |
Setup incoming webhook via portal
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
You can also use the command form LOW CODE → Commands → webhook.put in the portal to create a webhook without the CLI:
...
Trigger incoming webhook message from outside
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
| Note |
|---|
In order to secure the webhookUrl you should always prefer a HTTPS connection between the two systems and send the uuid parameter in the body of a POST request instead of GET. PIPEFORCE supports both methods. But it mainly depends on the caller of the webhook whether this external system supports POST calls. |
Consuming incoming webhook
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
| Note |
|---|
For security reasons, by default the webhook pipeline is executed with very limited anonymousUser privileges. So make sure that you use only commands in your pipeline which can be executed by this user. In case you need more privileges, you can use the iam.run.as command to switch to the privileges of the given user before executing the command. See the IAM portal for the permissions (=roles) of a given user. Also see Setup Permissions for more details on user privileges / permissions. |
Some words about security and webhooks
Since webhooks allow to execute pipelines, they can be very powerful. This power also comes with additional responsibility to you, the pipeline engineer. Make sure you have sufficient security testings in place and you have secured your webhook pipelines accordingly.
List existing incoming webhooks via CLI
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
| Code Block |
|---|
pi command webhook.get uuid=<yourWebhookUuid> |
List existing incoming webhooks via portal
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
In the portal go to LOW CODE → Commands → webhook.get and execute the form:
...
Edit or delete incoming webhook via CLI
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
And then set the uuid of the webhook you want to delete.
Edit or delete incoming webhook via portal
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
To edit or delete a webhook using the portal, go to Commands → webhook.put or Commands -> webhook.delete and execute the form accordingly.
Receiving multiple files with incoming webhook
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...
More information about multipart POST requests can be for example found here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
Outgoing webhook
An outgoing webhook is a url to be called from inside a pipeline in order to trigger something at an external system.
Send outgoing webhook
| Status |
|---|
| colour | Yellow |
|---|
| title | COMMUNITY |
|---|
|
| Status |
|---|
| colour | Blue |
|---|
| title | ENTERPRISE |
|---|
|
| Status |
|---|
| colour | Purple |
|---|
| title | CORPORATE |
|---|
|
...