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.

Quick guide to create a webhook

1. Create a new incoming webhook endpoint by using the command webhook.put.

2. Set the eventKey to the name of an event to be fired internally every time after this webhook has been received.

3. Remember the url or uuid of the webhook (is returned after it was created).

4. 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 automatically triggers the registration of the listener). This pipeline then will be executed every time this webhook is called.

5. 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>

6. 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.

Incoming webhook

...

Status
colour Blue title ENTERPRISE

Status
colour Purple title CORPORATE

An incoming webhook is an url endpoint created inside PIPEFORCE which can be called by an external system to trigger a pipeline inside PIPEFORCE. The url of such an incoming webhook has a format similar to this:

...

• Replace <NS> by your namespace.

• Replace <uuid> by the UUID of your webhook.

Setup incoming webhook via CLI

...

...

Status
colour Blue title ENTERPRISE

Status
colour Purple title CORPORATE

1. In order to create and setup a new incoming webhook, you can simply use the command webhook.put and the CLI:

   Code Block
   pi command webhook.put eventKey=<ID>

2. Replace <ID> by the name of the event which must be fired when this webhook gets triggered.
   Note: Its good practise to name event keys always lower case and separate it in groups separated by a dot with webhook. as the root group. For example:

   Code Block
   pi command webhook.put eventKey=webhook.github.update

3. After you have executed this command, a new webhook was created and the details about it will be returned as a JSON or YAML which looks similar to this:

   Code Block
   { "eventKey": "salesforce.lead.created", "webhookUrl": "https://hub-<NS>.pipeforce.net/api/v3/webhook.receive?uuid=885d...", "uuid": "885d...", ... }

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

Only:

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

...

...

colour	Purple
title	CORPORATE

After you have setup successfully the webhook, it can be triggered (called) from outside.

...

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

...

...

titleENTERPRISE

Status
colour Purple title CORPORATE

After you have successfully setup the webhook, any time the webhook url is called from outside, a new message is produced internally inside PIPEFORCE which then can be consumed by any pipeline. To do so, use the event.listen command to listen for such new event messages. Here’s an example which sends an email whenever a new lead in Salesforce was created using a webhook with the eventKey =webhook.salesforce.lead.created:

...

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 Groups, Roles, 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

...

...

To list all existing webhooks, you can use the webhook.get command:

...

Code Block
pi command webhook.get uuid=<yourWebhookUuid>

List existing incoming webhooks via portal

Only:

In the portal go to LOW CODE → Commands → webhook.get and execute the form:

...

Edit or delete incoming webhook via CLI

...

...

colour	Purple
title	CORPORATE

In order to edit an existing webhook, you can use the webhook.put command and set the uuid of the webhook to edit. For example:

...

And then set the uuid of the webhook you want to delete.

Edit or delete incoming webhook via portal

Only:

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

...

...

BluetitleENTERPRISE

Status
colour Purple title CORPORATE

Its also possible to send a playload like multiple files with a webhook. To do so, execute the request as multipart POST with the body formatted as multipart/form-data. For example:

...

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

...

...

To send a webhook to an external system, you can use the command webhook.send as this pipeline example shows:

...