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:
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
In a new flow, drag and drop the webhook trigger node onto the canvas to open up the settings panel.
Follow the prompts to set up your API token if you have forgotten it or it hasn't been generated before.
Copy the “POST URL” found under Configure Webhook trigger URL. This URL identifies this specific Pendula flow.
Paste link as the ‘POST URL’ in the Webhook configuration settings of the third party application.
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:
First name
Last name
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.
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:
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.
Webhook response body
When a payload is successfully received, Pendula returns a 202 Accepted response with a response body confirming the endpoint is correctly configured and the flow has been triggered.
This is particularly useful when testing your webhook using tools like Postman, as it provides immediate confirmation that your request reached the right endpoint and was accepted.
Example response:
Here's an example of the response body of the payload above, in JSON format:
The unique identifier of the Pendula flow that was triggered.
flowVersion
The version of the flow at the time it was triggered.
experienceId
The unique identifier for the specific experience instance created by this trigger.
A 202 Accepted response indicates the webhook payload was received and the flow has been queued to run. It does not guarantee the flow has completed execution.
Possible error responses
Error code
Description
400
An invalid Custom Context header was sent
404
The triggered flow is invalid, or authentication failed.
Pendula always returns a 404 Not Found response when a request is made to a Webhook Trigger endpoint without valid credentials. This behaviour is intentional and designed to enhance security—preventing unauthorised users from discovering or probing endpoint URLs based on response codes.
Even if authentication details are missing or incorrect, the system will not return an authentication-specific error (such as 401 Unauthorized). Instead, it will always respond with a 404 to prevent endpoint enumeration.
If you're troubleshooting a webhook request failure, ensure that your credentials are correctly configured and that the external system sending the request includes the expected authentication details.
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.
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.
In Integrations, under Connections, locate the 'Active' API token you wish to deactivate.
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.
In the Integrations page, locate the 'Inactive' API token you wish to reactivate.
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.
In the Integrations page, locate the API token you wish to delete. Note that an API token must be 'Inactive' to be deleted.
Under the Actions column, select Delete API token. Follow the prompts to continue.
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.
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.
Give a unique, helpful name to the credentials.
Add an optional description to further describe what the credentials are used for (e.g. Sales CRM authentication).
Enter credentials key-value format.
Save credentials.
Adding a bearer token
A bearer token is a string that is passed in the Authorization header of the HTTP request.
Give a unique, helpful name to the credentials.
Add an optional description to further describe this integration.
Enter bearer token.
Save credentials.
Adding a username and password
Username and password that is passed in the Authorization header of the HTTP request.
Give a unique, helpful name to the credentials.
Add an optional description to further describe this integration.
Enter username and password.
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.