The Incoming webhook trigger listens for events in the external application and triggers automation in real-time. This trigger requires a listener URL that serves as the endpoint to which the external application sends the webhook event details.
Overview
The Incoming webhook trigger enables you to create triggers for applications that support webhooks. The trigger requires a listener URL that serves as the endpoint for receiving the event data. Use the Create listener option in the Listener URL tab of the Event Triggers page to create the listener URL. Once the system generates this URL, you cannot edit it. After you create the listener URL, add it as the callback URL in the integration settings of the external application. When the event occurs, the application sends a POST API call to the trigger with event data as the payload. The event data is in key-value pair format and can be used in downstream actions within the automation.
The Incoming webhook trigger supports event data content types in
the following formats: plain text, XML, JSON, multipart data, and form-urlencoded.
The system automatically converts the event data in plain text and XML formats to
key-value pair format. The string response serves as the key, and
the plain text or the XML file content serves as the value. In the case of
file-based multipart data, the trigger processes only the metadata of the files.
The Audit log records the event data as Bot run by trigger event type in key-value pair format. The event data payload must not exceed 1 GB.
The Incoming webhook trigger provides options to add authentication headers and signature schemes based on the application for which you are configuring the trigger. You must set the authentication headers in the webhook settings of the application and add the same headers in Authentication headers. You can also set a security scheme for validating the incoming payload. Set the X-Signature header with the key on the application side and add the same parameter and key in the Signature scheme field. Currently, the Incoming webhook trigger supports HMAC-SHA256 signature only.
Challenge-based webhook validation
The Incoming webhook trigger now supports challenge-based webhook validation. This validation verifies the ownership of the listener URL before delivering the event notifications to the automation. The Verify Listener ownership toggle on the Create listener modal enables the challenge-based verification.
The external application sends a POST call that contains the challenge code in a query parameter, request body, or request header as the validation request to the listener URL of the Incoming webhook trigger. The trigger automatically reads and validates the code by returning an HTTP 200 status with the challenge code as the response payload. If the challenge is encoded in a URL-encoded request body, the Incoming webhook trigger automatically decodes it before validating it. The trigger configuration fails if the validation toggle is disabled when creating listener URLs for applications that require a challenge-based webhook validation.
Settings
The following settings are available in Listener trigger:
- Incoming webhook
- Choose an appropriate listener URL for the trigger from the drop-down list.Listener trigger. You can use the Refresh button to refresh the drop-down list. For more information about creating listener URLs, see Creating listener URL for Incoming webhooks.
- Authentication headers
- Enter the authentication headers that you set on the application side. The authentication headers ensure that the webhooks are secure. The headers use the name-value format. Ensure that you enter the exact name and values that you configure in the application settings. This field is optional.
- Signature scheme
- Select an appropriate signature scheme to validate the incoming data. The signature scheme verifies the data origin and integrity, providing an additional security layer. The signature scheme consists of a key identifier and a header name.
- Secret key
- Enter the secret key used to identify the signature. Use the Credential option to choose a key that is available in the Credential Vault. Alternatively, enter the key directly in the Insecure string option.
- Signature header name
- Enter the header name for the secret key.
- Response
- Select a record variable to save the trigger response data. The automation saves the trigger response data in a key-value pair format. Refer the API documentation of the external application for the response data payload.