Making Contentful speak to Slack
In traditional CMSes, collaboration — if available — is baked into the CMS itself. We feel there is a better approach: if your CMS happens to be a microservice, it can interact with the tools you already use, and integrate into your existing workflows. Chances are that the tool is Slack.
Everyone's on Slack anyway
For our own small editorial team we wanted a transparent way to see who's writing what, preferably real-time and without extra manual work (like filling a spreadsheet). We realized that we're all on Slack already, and using tons of 3rd party integrations. Why not have Contentful send messages to Slack whenever content is updated?
Given that so many teams across the world are already on Slack as well, it suddenly made even more sense: whatever we make, others would be able to use it, too.
Hey, it works!
A few days of researching and coding by Frederik, our Solution Architect, led to making it happen. Just look at this beauty:
Whenever content is edited, the bot tells about it in a dedicated channel
The integration is quite basic, but it does its job: whenever content is edited in the Contentful space which powers our website (including this very post), the bot tells about it in a dedicated channel. Note that the message contains the author's name, link to the entry, and an excerpt from the updated piece of content. Makes it surprisingly simple to either talk to the author, if necessary, or click the link to open the entry in Contentful.
The building blocks
There are four essential components behind this integration:
Webhooks. Contentful has to send a webhook every time it notices that content is being edited.
The AWS API Gateway is used to create a simple endpoint which maps data between the Contentful webhook and our Lambda function.
AWS Lambda. A 150-line Node.js function which is running on the AWS Lambda service.
Slack API. This Lambda function finally calls the Slack API to send the message.
Here's a diagram to make it slightly more understandable:
Contentful sends a webhook to a function running on AWS Lambda which does a few nice things and then calls the Slack API to send the message
Why Lambda
Ideally, we'd send a webhook from Contentful to the Slack API directly, so that no intermediary code would be required. That would not work though.
First, Slack has a specific API format, which requires putting the message text into the JSON payload – and fine-tuning the payload is not something that the Contentful webhooks configurator is supposed to be used for.
Second, we want to show the author's name in the messages: that is, to display Leopold Bloom instead of 3NL4TQpO8wuQecAqi0iGgI. To convert user IDs into their names, a call to the Content Management API is necessary – since the webhook doesn't know anything about their names – which is another task that this function is dealing with.
Set it up for your team
First, get the integration. To set it up, you’ll either need to know a thing or two about webhooks and AWS Lambda yourself, or ask a friendly developer for some help. In the spirit of brevity we won't spell out step-by-step instructions. Here are some general directions instead, and some important details which you should know about.
Create the webhook target API at AWS API Gateway, similar to what you see in swagger.json.
Create your AWS Lambda function and connect it to the API target from the previous step.
Set up the integration for the headers, similar to what you see in integrations.json, and deploy your API.
Set up a webhook in your Contentful space and point it to your API target.
Set up an integration in the Slack customization directory.
Edit
lambda.json: replacecmaTokenwith your Contentful Management API token, andslackURLwith the url of your incoming webhook on slack.
That's pretty much it. See the important details below – and shall something not work, tweet this way.
Don't skip these details
The data we send to Slack is a mix of the HTTP headers and the body of a Contentful webhook.
Make sure to pass
X-Contentful-TopicandX-Contentful-Webhook-Nameto the lambda function.You might want to create a user for the Management API which has read-only access to your space. You can then use a token of this user to communicate with Contentful from AWS Lambda.
You might also find contentful-webhook-listener.rb an interesting project to look at in terms of interacting with Contentful webhooks.
What will you build?
What other extensions and integrations do you expect from Contentful? Tell us on Twitter – we’d love to know.
