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 "http://localhost:9081/inbound/helloasmr"
    -H "Authorization: Bearer {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.

When manually typing out mergefields, mergefield with hyphens - or a full stop . need a square bracket to be valid. For example, {{inboundMessageTrigger.[user-id]}} and {{inboundMessageTrigger.[user.id]}} are valid, and {{inboundMessageTrigger.user-id}} and {{inboundMessageTrigger.user.id}} would cause an error.

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

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 preserved. This means that if both the original and the duplicated flows are active, a POST request to that URL will trigger both flows simultaneously.

Pendula does not currently warn users about this potential issue.

To avoid this, the user needs to replace the webhook trigger in the duplicated flow to avoid conflicts.

Assuming the sample payload is going to be the same as the original flow,

• Duplicate the flow. 
• In the duplicated flow, copy the sample payload from the Webhook trigger (inboundWebhookTrigger_1 )
• Replace the existing Webhook trigger with a new one (inboundWebhookTrigger_2 )
• Add the sample payload back into the new webhook trigger.
• Update any merge fields referenced in later nodes.