Reference
Webhook trigger node

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

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.