Building a Slack Integration
In this tutorial, we'll build a basic Slack integration that sends notifications from your app to your customers' Slack accounts.
Last updated
In this tutorial, we'll build a basic Slack integration that sends notifications from your app to your customers' Slack accounts.
Last updated
This guide demonstrates how to sync data from your app to your customer's Slack accounts. For demonstration purposes, we’ll build a workflow that sends a notification to our user's Slack using event data from our app. You can use the concepts covered in this tutorial in other applications as well.
Add your Slack app credentials to activate your integration.
It's important that you give your workflows a descriptive name to provide the best experience for your user.
Since we want to pass event data from our application to our customer's Slack account, we'll use the App Event trigger. Select the trigger step from the Workflow Editor, then click "App Event".
Select Choose an App Event > Create new App Event, then add the following parameters:
Event Name - the name of your App Event. (e.g. Lead Created)
Event Schema - example JSON Object that will be sent from your app. JSON objects are written in key/value pairs. Keys must be strings, and values must be a valid JSON data type (string, number, object, array, boolean or null)
You can use the sample App Event Schema below to jumpstart your progress:
Add a Slack step to your workflow and use the dropdown menu to select Send message in channel as the action. When composing your message, you can input the fields from your App Event by typing two left curly braces {{ to bring up the dynamic variable menu.
Step 1.4: Create a User Setting
Since we want our user to select which channel in Slack we should send new notifications to, we will add a User Setting to our workflow.
To add Workflow User Setting to Slack, follow these steps:
Click Customize Connect Portal in the Overview page to open the Connect Portal Editor.
Click the Configuration tab in the right sidebar.
Click on the workflow you'd like to add User Settings to.
Under User Settings in the right sidebar, click + Add Settings.
Enter a name for the field and choose the Channel field type from the dropdown menu.
Click the Save button to add it to your Connect Portal.
Navigate back to your workflow once you have added the User Setting. Click into the Slack step and input the fields from your App Event by typing two left curly braces {{ to bring up the dynamic variable menu.
Now that your workflow is all set up, deploy your workflow by clicking the "Deploy" button in the top-right of your screen.
To generate a Signing Key, go to Settings > Signing Keys in your Paragon dashboard. You should store this key in an environment secrets file.
For security reasons, we don’t store your Private Key and cannot show it to you again, so we recommend you download the key and store it someplace secure.
The Paragon SDK gives you access to the Paragon global, which you can access as paragon.
You can install the Paragon SDK with npm:
The SDK can be imported in your client-side JavaScript files as a module:
Next, you'll need a library in your target language to sign JWTs with RS256. You can find one in your language at https://jwt.io/.
If your application is a fully client-rendered single-page app, you may have to create and use an additional API endpoint to retrieve a signed JWT (or reuse an existing endpoint that handles authentication or user info).
The Paragon User Token is a signed JWT that minimally must include the sub, iat, and exp claims:
Just for testing: Generating one-off JWTs
Use the Paragon JWT Generator to generate test JWTs for your development purposes. In production, static tokens should never be used.
You'll call paragon.authenticate in your view with a JWT signed by your backend using the library chosen in Step 4.1. This JWT is the Paragon user token.
.authenticate should be called at the beginning of your application's lifecycle in all cases. This is to make sure that the userToken is always as fresh as possible, with respect to your user's existing session on your own site. You may reference Installing the Connect SDK for a detailed explanation on how to use .authenticate.
Now that you've authenticated your user, you can call paragon.connect() to bring up the Paragon Connect Portal.
Note: Toggle your workflow from the Configuration tab to enable your workflow after connecting to your Slack account.
Lastly, we'll send an App Event whenever a lead is created in your app. App Events can be sent from your application using the Paragon SDK or REST API. In both cases, you must pass two parameters:
name - the event name defined in your App Event
payload - the event payload that should match the event schema defined in your App Event
See the code examples below for how to send App Events using the Paragon SDK or API.
When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.
Great work! We just built a Slack integration that sends new notifications from your app to our customers' Slack accounts.
