Utilize webhooks and our API endpoints to send notifications to your learners in Slack
In this article we will explain how to send a setup a simple integration between EdApp and Slack, that can notify your learners when a Rapid Refresh quiz is available for them to complete.
Please note that Rapid Refresh session notifications are sent at 9am to the users in their local timezone. If your user does not have a time zone set, you can set it using the EdApp Public API update user endpoint.
Please see our Public API documentation for the list of available webhook events.
- 1. Link your Slack and EdApp users
- 2. Create a workflow in Slack
- 3. Find your EdApp Public API Token
- 4. Link your webhook to an event using the EdApp Public API
- 5. Configure your Slack Webhook
1. Link your Slack and EdApp users
In order to send EdApp notifications to your users in Slack, we must link the users in both systems together. There are two options:
Option 1. Link your users via Email address
If your Slack users and EdApp users have the same email address, this can be used to link them together (skip on to section 2).
Option 2. Link your users via the EdApp External ID
If your Slack users and EdApp users have different email addresses, you can still link them together using the EdApp External ID.
A. Find your Slack member ID by going to View Profile > More > Copy member ID
B. Paste the Slack member ID into the External ID field of the related EdApp user. See Configuring User Permissions for more details.
This manual process works well for a small number of users. However, if you need to link many users, we recommend updating your users External ID's through the EdApp Public API update user endpoint.
2. Create a workflow in Slack
A. In Slack, navigate to Go > Workflow Builder.
B. Click the Create button, name your workflow, and click Next.
C. Select the Webhook option and then click Add step.
D. The workflow needs a step in order for us to Publish it. Select Send a message.
E. Send a test message do yourself. The contents of the message are not important, as we will update this in section 5.
Once you've entered a message, click Save, and Publish your workflow.
F. This generates a webhook URL, which you'll need when calling the EdApp Public API below.
3. Find your EdApp Public API Token
Go back to EdApp, click on the dropdown next to your username > API Details.
Here you will find your token for calling the EdApp Public API.
4. Link your webhook to an event using the EdApp Public API
Now you need to create a "link" between the webhook you have created in Slack, and an event in EdApp.
Using a tool that can make API requests, like Postman, you can call the POST /v2/webhooks endpoint to create this link. Ensure you are supplying your API token in the Authorization header (see Authenticating and using the EdApp API)
Supply a request body:
"eventName" : "RapidRefreshSessionStartedNotificationEvent" // Or another available event
"webHookUrl" : "https://..." // The webhook URL that was generated by Slack
When you make this request, you should receive a response back like so:
"webhookId" : "my-webhook-id",
The messageFormat object shows the format of the data that will be sent to the webHookUrl when the event happens.
5. Configure your Slack Webhook
A. Go back to Slack and Edit your webhook.
B. Click Add Variable.
C. Input userExternalID (provided in the messageBody from EdApp) into the Key field, and select Slack user ID as the data type.
ℹ️ If you have instead linked your users via email address, you can add a variable email and select data type Slack user email.
D. Repeat the same steps adding two more variables:
- quizTitle (Data type: Text)
- quizLink (Data type: Text)
(You may add any variables that are provided in the messageFormat)
Save your webhook.
E. Edit the test message you provided earlier.
F. In the field "Send this message to", you can now select userExternalId - since this will contain a Slack ID we added to EdApp, this will ensure the correct user gets a message.
You can also customise the message text with the available variables you've configured.
Save your webhook.
Test your notification
Now, whenever the event you have subscribed to occurs in EdApp, you will get a message similar to the following: