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:

...

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...", ... }

...

Setup incoming webhook via portal

Only:

...

Trigger incoming webhook message from outside

...

colour	Purple
title	CORPORATE

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

...

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.

...

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:

...

Edit or delete incoming webhook via portal

Only:

...

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:

...

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:

...