Outgoing Webhooks (HTTP Requests with Rules Engine)

The Rules Engine can be used to connect to external services and automate tasks outside of Brightidea by sending HTTP Requests when certain events are triggered. These requests can trigger further actions, with or without passing data about the idea.

This is sometimes referred to as an outgoing webhook. Brightidea sends the request to another service's incoming webhook, enabling the two systems to communicate and pass data in a low-friction way.

Before getting started:

Review the Rules Engine article if you are not yet familiar with general functionality of setting up rules and automation
"HTTP Requests" were formerly named "Post to URL," and were more limited in functionality; this has been updated in Spring 2021
Make sure you know where the request is going and what data formats are expected, as the rule cannot be configured without this information

Getting Started with HTTP Requests
- Constructing an HTTP Request
Examples

Getting Started with HTTP Requests

After configuring necessary triggers and conditions for a rule, select 'HTTP Request' from the actions section. Actions can be stacked, so multiple HTTP requests can be combined or even paired with disparate action types.

Constructing an HTTP Request

To construct the HTTP request action, you'll need to understand how the receiving service expects to receive requests and data. Once you have the target service set up and understand its requirements, complete the following:

Select the method as either GET or POST
Next, you will need to paste the target URL from the service that is receiving the request. See below for a few examples with tips on where to find this information, and what it will look like. It usually can be found as incoming webhook and typically includes a unique ID.
Select the content type as either URL Encoded Form or JSON
Enter any required headers; if none are necessary, enter HDR1:hdr1 as dummy data
Finally, enter the parameters you want to send or the JSON-formatted body of the request, corresponding to your content type selection. Dynamic fields can be used in this section to send various data properties from the idea. Use the dropdown and click the "+" to automatically insert the corresponding dynamic field parameter. These are also listed below for reference.

Be sure to click save, make sure the rule is in the correct order, and then set it to 'active.' The HTTP request will now fire when the trigger & conditions are met.

Dynamic Fields

[AFFILIATE_ID] [AFFILIATE_NAME] [ACTIVITY_ID] [ACTIVITY_NAME] [CONTACT_EMAIL] [EMAIL] [IDEA_CODE] [IDEA_TITLE] [IDEA_DESCRIPTION] [IDEA_URL] [IDEA_ID] [IDEA_DESCRIPTION] [IDEA_SUBMITTER_SCREENNAME] [IDEA_SUBMISSION_FORM_ADDITIONAL_QUESTIONS]

Note: "Webstorm" has been deprecated and replaced with "Activity" but will still work for legacy rules.

Examples

While the following examples are provided for inspiration and guidance, HTTP Requests are by no means limited to these actions. Think about how you might:

Combine workflows with another web app's "incoming webhook" functionality
Send requests to a custom web service
Leverage a connector service like Zapier to integrate with preconfigured actions from thousands of other services

Note:

Third party screens, workflows, and capabilities may change at any time. The following were documented in March 2021.
JSON code has been compacted for inline display & ease of copy-paste; we recommend using an editor to improve readability when editing JSON contents

1 - Posting Updates to Slack

For more details, see the dedicated article: Brightidea Slack Integration.

In this rule, we will post notifications to a Slack channel when ideas are selected for implementation. This could easily be adjusted to post when new ideas are submitted, when statuses are changed, when ideas become stale...or all of the above!

Similarly, you could post to a channel when comments are made on ideas.

In Slack

First, configure an 'Incoming Webhook' from the 'App Directory' in Slack (can usually be found at [your-workspace].slack.com/apps):

Screen_Shot_2021-03-09_at_5.37.08_PM.png

The form should be straightforward, but follow the guide above
Personalize the integration with customizations such as icon and user/bot name

In Brightidea

Create a rule to trigger when ideas reach a "selection" step:

Method: Post
URL: Copy and paste from your Slack configuration above
Content type: URL Encode Form
Header: HDR1:hdr1
Parameters: start with the sample code below, but first replace the #idea-selected channel with your own

Screen_Shot_2021-03-09_at_5.49.28_PM.png

Copy and paste from the example to get started (replace channel name with your own):


        payload={"channel": "#idea-selected", "attachments":[

        {"fallback":"An idea was submitted to the Idea Box.",

        "pretext":"An idea was submitted to the Idea Box.",

        "color":"#A9A9A9",

        "fields":[

        {"title":"[IDEA_TITLE]",

        "value":"https://bi.brightidea.com/[IDEA_CODE]",

        "short":false }]}]}

This will post a simple message to your selected channel, similar to the following:

Advanced Slack Integration

To do even more, check out the Incoming Webhooks article from Slack. Changing to JSON content type will allow you to post even more interactive messages to Slack using the block kit.

2 - Posting Updates to Microsoft Teams

Like the Slack example above, we will create a rule that posts notifications to a Teams channel when a trigger and conditions are satisfied. This is a great way to customize and post notifications for a group of people into a single online hub. For example, a small team wants to monitor new submissions to their Idea Box in an MS Team where they are already working together.

In Teams

Configure an 'Incoming Webhook' connector:

Use the example above as a guide
Customize the integration name and logo that will show in the channel when updates are posted

In Brightidea

Create a rule to:

Method: Post
URL: Copy and paste from configuration window above
Content type: JSON
Header: HDR1:hdr1
Body: start with the sample code below to post a simple card to Teams, being sure to replace [your-brightidea-url] with your Brightidea web address (usually company.brightidea.com)


        {"type":"message","attachments":[{"contentType":"application/vnd.microsoft.card.adaptive","contentUrl":null,"content":{"$schema":"http://adaptivecards.io/schemas/adaptive-card.json","type":"AdaptiveCard","version":"1.2","body":[{"type":"ColumnSet","columns":[{"width":"32px","items":[{"type":"Image","width":"16px","horizontalAlignment":"Center","url":"https://d1dxeoyimx6ufk.cloudfront.net/uploads/WWW/OD38/1BE73BAA.png","altText":"Brightidea
        Logo"}],"type":"Column","padding":"None"},{"width":"stretch","items":[{"type":"TextBlock","text":"Brightidea
        - [AFFILIATE_NAME] - [ACTIVITY_NAME]"}],"type":"Column","padding":"None"}],"padding":"None"},{"type":"ColumnSet","spacing":"Large","separator":true,"columns":[{"width":"stretch","items":[{"type":"TextBlock","isSubtle":true,"text":"A
        new idea was submitted"},{"type":"TextBlock","text":"\"[IDEA_TITLE]\"
        by [EMAIL]"}],"type":"Column","padding":"None"}],"padding":"None"},{"type":"Container","items":[{"type":"ActionSet","actions":[{"type":"Action.OpenUrl","title":"View
        Idea","url":"https://[your-brightidea-url]/[IDEA_CODE]"}]}],"padding":"None"}]}}]}

Save the rule

When triggered, the result should look something like this in your Teams channel:

Advanced Teams Integration

We recommend using Microsoft's Adaptive Card Designer to design more advanced layouts and interactivity. An editor that supports human-readable JSON format is also helpful. Many additional resources can be found for learning more about adaptive cards.

3 - Creating Issues in Jira

For this integration we will automate the creation of Jira issues for ideas that have been selected for implementation, feeding directly into the development pipeline.

In Jira

Navigate to 'Automation Rules' in Jira's System Setup and create a new rule to handle the incoming request.

Set up a trigger using the 'Incoming webhook' option

A Webhook URL will be provided (you'll paste this into the Brightidea rule)
In this example, we will create new issues from the idea, so select Issues provided in the webhook HTTP Post body

Add an action to the rule to 'Create Issue'
Note: it is also useful to add logging actions when trying something new or troubleshooting, as seen below

Be sure to use correct formatting to extract the data; see Jira documentation for more details. The simple example below is not a general solution as it corresponds to how we plan to format the JSON in the Brightidea rule in the following section:

Summary (Title) will use the Brightidea idea title:


        {{webhookData.Idea.IdeaTitle}}

Description will consist of several idea data properties:


        Affiliate: {{webhookData.Activity.AffiliateName}} ({{webhookData.Activity.AffiliateID}})
Activity: {{webhookData.Activity.WebstormName}}

{{webhookData.Idea.IdeaTitle}} ({{webhookData.Idea.IdeaCode}})
by
{{webhookData.Idea.SubmitterEmail}}

{{webhookData.Idea.Description}}

{{webhookData.Idea.IdeaURL}}

Save the Jira rule

In Brightidea

Create a rule:

Method: Post
URL: Copy and paste from configuration above
Content type: JSON
Header: HDR1:hdr1
Body: start with the sample code below to send the dynamic fields to Jira. Remember, this corresponds specifically to our Jira rule configuration above.


        {"Activity":{"AffiliateName":"[AFFILIATE_NAME]","AffiliateID":"[AFFILIATE_ID]","WebstormName":"[WEBSTORM_NAME]","WebstormID":"[WEBSTORM_ID]","ContactEmail":"[CONTACT_EMAIL]"},"Idea":{"SubmitterEmail":"[EMAIL]","IdeaCode":"[IDEA_CODE]","IdeaTitle":"[IDEA_TITLE]","IdeaID":"[IDEA_URL]","IdeaDescription":"[IDEA_DESCRIPTION]","IdeaURL":"[IDEA_ID]"}}

Save the rule

When triggered, the result should look something like this in Jira:

4 - Using Zapier to Connect to Thousands of Services (e.g. Create Trello Ticket)

This example will show how to connect to Zapier, which opens up access to any number of actions on numerous services. In this case we will create a Trello card for ideas that our project manager wants to track separately.

In Zapier

Begin configuring a Zap with 'Webhooks by Zapier' and follow the prompts to get a URL:

In Brightidea

Open Brightidea and create a rule:

Method: Post (to match Zapier configuration)
URL: Copy and paste from configuration above
Content type: JSON
Header: HDR1:hdr1
Body: start with the sample code below to send all of the dynamic fields to Zapier


        {"Activity":{"AffiliateName":"[AFFILIATE_NAME]","AffiliateID":"[AFFILIATE_ID]","WebstormName":"[WEBSTORM_NAME]","WebstormID":"[WEBSTORM_ID]","ContactEmail":"[CONTACT_EMAIL]"},"Idea":{"SubmitterEmail":"[EMAIL]","IdeaCode":"[IDEA_CODE]","IdeaTitle":"[IDEA_TITLE]","IdeaID":"[IDEA_URL]","IdeaDescription":"[IDEA_DESCRIPTION]","IdeaURL":"[IDEA_ID]"}}

Return to Zapier

Continue to follow the prompts to configure the action with test data:

Send a test request by triggering the rule. It should come across nicely like this:

Select the action to perform. For us, we will create a Trello card using the fields from above
The Zapier interface will assist with this process depending on what app you have chosen to integrate with: