Webhooks & web requests

Webhook trigger: Setting up an API token

The Webhook Trigger node listens for information in real-time from an external application to trigger a Pendula flow. 

What is a Webhook?

A webhook is a way for an application to automatically exchange real-time data with other applications. It functions as an HTTP request triggered by an event in a source application and sent to a destination application with a data payloadInsert definition here. This allows one application to "speak" to another in real-time, sharing information about the event. For example, a telco provider can use webhook to notify Pendula whenever a new customer activates a service. When the event occurs, the source system (telco provider) sends an HTTP POST request to the destination system (Pendula) with activation details. Upon receiving the payload, the webhook trigger in Pendula initiates an experience, such as sending a welcome message or service confirmation to the customer. This automated communication enables immediate data transfer without manual intervention.

Usage scenario

The following example demonstrates a practical application of the Webhook Trigger within a flow, that sends an onboarding message following a new service subscription. When a user signs up for a new subscription, the source system is configured to send a payload to a webhook URL. Here is an example request body of a payload:

{ 
  "user-id": "harrison-example", 
  "firstname": "harrison", 
  "lastname": "koenig", 
  "mobile": "+61400000000" 
}

Upon receiving a webhook, Pendula triggers an experience designed for new subscribers. This flow could include actions like sending a welcome message, providing important information about the service, or scheduling follow-up interactions.

Configuring this trigger

1. In a new flow, drag and drop the webhook trigger node onto the canvas to open up the settings panel.
   
2. Follow the prompts to set up your API token if you have forgotten it or it hasn't been generated before.
3. Copy the “POST URL” found under Configure Webhook trigger URL. This URL identifies this specific Pendula flow.
4. Paste link as the ‘POST URL’ in the Webhook configuration settings of the third party application.

Learn more about which configuration method should be used.

What is a payload?

A payload is the data sent from one application to another when an event occurs. This data is included in the body of the HTTP request and typically contains detailed information about the event that triggered the webhook. For best practices -

• The request must be in JSON format.
• The minimum recommended payload inclusions are:
  1. First name
  2. Last name
  3. Mobile number
• The payload must be less than 200 KB

Here's an example of how to format your payload:

curl -X POST --location https://{{ Replace with your Pendula domain }}/
webhook/inbound/{{ Replace with ID from flow builder }}
-H "Authorization: Basic {insert token}"
-H "Content-Type: application/json"
    -d "{
        "user-id": "harrison-example",
        "firstname": "harrison",
        "lastname": "koenig",
        "mobile": "+61400000000"
        }"

Validate payloads and use webhook merge fields

To validate your webhook and use the webhook data as merge fields later in the flow, Pendula allows you to paste a sample payload into the Merge fields tab of the webhook trigger node.

Learn more about Pendula and merge fields.

Simply copy the request body of the payload (not including headers) and paste into the sample payload field. The sample payload must be in JSON format (key value pairs with hierarchy)

Here's an example of the request body of the payload above, in JSON format:

{
  "user-id": "harrison-1a2b3c4d",
  "firstname": "harrison",
  "lastname": "koenig",
  "mobile": "+61400000000"
}

Note that any sample properties with 'null' values can't have a type, and sample value, inferred from them. Please only provide sample properties with not-null values.

Possible error responses

Duplicating a flow with a Webhook trigger

When a user duplicates a flow with a Webhook Trigger, the POST URL in the webhook trigger is automatically regenerated.

This means that the new flow has a new address, and you will need to update the system sending the inbound webhook to the new address if you wish to trigger the duplicated flow.

1. Navigate to Integrations > Setup connection > API token.
   
2. You will be prompted to provide a helpful Name and Description. Then, click Generate.
   
3. Once generated, the API token is shown in two different formats (HTTP header or basic authentication) and either can be used to secure inbound payloads to Pendula.

   Make sure to store the generated API token securely, as this cannot be shown again.

   
4. Ensure the credentials are saved securely, check the I have saved these credentials securely checkbox, and select Done. Now you can use this API Token to authenticate inbound payloads to the webhook trigger in the Flow builder.

Editing API tokens

You can edit Name and Description of an API token. Click on settings, make the changes and click on Update connection.

Deactivating API tokens

You can deactivate API tokens that are no longer used, or for which access is no longer authorised, at any time. Once deactivated, services using this API token will no longer be authenticated. 

1. In Integrations, under Connections, locate the 'Active' API token you wish to deactivate.
2. Under the Actions column, select Deactivate API token. Follow the prompts to continue.
   

   Note that API tokens can take up to 60 seconds to be deactivated.

Reactivating API tokens

You can reactivate API tokens that have previously been deactivated (represented by the 'Inactive' status) in order to authenticate services using the API token.

1. In the Integrations page, locate the 'Inactive' API token you wish to reactivate.
2. Under the Actions column, select Reactivate API token.
   

   Note that API tokens can take up to 60 seconds to be reactivated.

Deleting an API token

You can permanently delete 'Inactive' API tokens. Note that this cannot be undone, and services using this API token will no longer be authenticated.

1. In the Integrations page, locate the API token you wish to delete. Note that an API token must be 'Inactive' to be deleted.
2. Under the Actions column, select Delete API token. Follow the prompts to continue.

Webhook trigger node

A webhook is a way for an application to automatically exchange real-time data with other applications. It functions as an HTTP request triggered by an event in a source application and sent to a destination application with a data payloadInsert definition here. However, the process of setting up webhooks can vary based on the capabilities of the third-party applications involved.

What are configuration methods?

Configuration methods refer to the different ways you can set up and manage the parameters required for integrating Webhooks with third-party applications. These parameters typically include the webhook URL (where the webhook data is sent), authentication details, and any custom headers needed for the requests. Webhook URL is a specific type of HTTP callout URL used for webhooks, where the URL is designated to receive automated HTTP requests triggered by specific events in the source system.

While many third party apps can trigger webhooks, how simple or complex this is will depend on the third party app itself. Below are different configuration methods, starting with the simplest:

Configuration within Third Party via Basic Auth

Using Basic Authentication is a secure way to ensure that only authorised systems can communicate with the webhook trigger. This configuration is ideal when the third party allows specifying both an HTTP Callout URL and Basic Authentication details (username and password).

• HTTP Callout URL

  This is the endpoint where the third party will send HTTP requests. Specify Pendula’s inbound webhook URL in the third party system’s settings.

• Basic Authentication

  Use a combination of a username (typically the tenant ID) and a password (Pendula’s Inbound API token) for authentication. These credentials should be included in every request to ensure secure communication.

Example configuration

Webhook URL: <https://api.pendula.com/webhook>
Username: tenant123
Password: api_token_abc123

To test the configuration, you can use a curl command to simulate a POST request with Basic Authentication:

curl -X POST <https://api.pendula.com/webhook> \\
     -u tenant123:api_token_abc123 \\
     -H "Content-Type: application/json" \\
     -d '{"event":"customer_update","data":{"id":"1234","status":"active"}}'

• X POST: Indicates that the request method is POST.
• u tenant123:api_token_abc123: Supplies the Basic Authentication credentials (username:password).
• H "Content-Type: application/json": Sets the request header to indicate that the body content is in JSON format.
• d '{"event":"customer_update","data":{"id":"1234","status":"active"}}': Provides the actual data being sent in the request body, formatted as JSON.

Other methods

Configuration within Third Party via Custom Headers

Use this if the third party allows specifying:

• HTTP Callout URL - This is where the Pendula’s Inbound webhook URL can be specified.
• Custom Header to be attached on every request. This is another way of specifying Pendula’s Inbound API token.

Example configuration

Webhook URL: <https://api.pendula.com/webhook>
Custom Header:
    Key: Authorization
    Value: Bearer api_token_abc123

curl -X POST <https://api.pendula.com/webhook> \\
     -H "Authorization: Bearer api_token_abc123" \\
     -H "Content-Type: application/json" \\
     -d '{"event":"customer_update","data":{"id":"1234","status":"active"}}'

Calling via a Simple HTTP Proxy Server

Use this if the third party:

• Does not allow specifying an http callout url
• Allows a HTTP proxy application to be running in their tech stack

To set this up, a proxy server must be configured to receive requests. The proxy server then forwards requests to Pendula.

Calling via a Simple Intermediary Application

Use this if the third party does not allow specifying an HTTP callout URL and requires integrations to follow an app approach.

To set this up, an intermediary app must to configured to receive and forward requests to Pendula. An intermediary app may process and modify the data before forwarding.

Configuration via Third Party Code

Use this if third party integrations are specifying using a code configuration approach. The code would send authenticated requests to Pendula.

Pendula can authenticate each HTTP request made with Make a web request using secure credentials. Having a credential with the request ensures the communication between Pendula and the external application is secure, and is required in some cases. Currently, Pendula supports securely storing: request headers, bearer token and username and password.

• Request Headers: Similar to instructions on a parcel, request headers define the handling and processing of data in a web request. These headers provide the server with details such as data format, handling procedures, and additional context for processing the request. Pendula securely records these specifications as key-value pairs, catering to a variety of operational requirements including content type, caching policies, and identification protocols.
• Bearer Token: This security token acts as a digital access card, granting entry to specific services after a successful authentication. It streamlines the validation process, allowing for a secure yet effortless way to repeatedly assert one's access rights without constant re-authentication. Pendula's storage solution securely retains these tokens, automating their inclusion in requests to services that mandate verified access.
• Username and Password: These traditional identifiers serve as a fundamental method of authentication. When a system necessitates such a verification method, Pendula's secure storage ensures these credentials are safely stored and accurately transmitted. This preserves the integrity and confidentiality of the user's access credentials.

Adding credentials to Pendula

In the Integrations page, go to Setup new connection and select Web request credentials.

Then, you will need to select the type of credentials you wish to store.

Adding a request header

Request headers are key-value pairs that are in the header of the HTTP request.

1. Give a unique, helpful name to the credentials.
2. Add an optional description to further describe what the credentials are used for (e.g. Sales CRM authentication).
3. Enter credentials key-value format.
4. Save credentials.

Adding a bearer token

A bearer token is a string that is passed in the Authorization header of the HTTP request.

1. Give a unique, helpful name to the credentials.
2. Add an optional description to further describe this integration.
3. Enter bearer token.
4. Save credentials.

Adding a username and password

Username and password that is passed in the Authorization header of the HTTP request.

1. Give a unique, helpful name to the credentials.
2. Add an optional description to further describe this integration.
3. Enter username and password.
4. Save credentials.

Adding saved credentials to web requests

After securely storing your credentials in Pendula, you can easily select them within the Make a Web Request node. This node allows you to execute HTTP requests as part of your automated workflows. By selecting saved credentials during the node configuration, Pendula ensures that each web request it makes on your behalf is authenticated, thus maintaining the security and integrity of data exchanges with external services.

For a detailed guide on configuring the make a web request node, see Make a web request Date Action

Updating credentials

1. Navigate to Integrations > My integrations
2. Under Action connections, select on the settings icons of the credential you want to update.
3. Update fields, Name and Description, as necessary.
4. Click on Update connection.

You cannot read credentials before updating them as they are stored securely and cannot be surfaced.