Extensions & Integrations
Webhook Notifications
apostrophe-external-notifications
A simple way to get notifications via Slack and other external systems when various events occur in ApostropheCMS.
Installation
# In the root dir of your existing apostrophe project
npm install apostrophe-external-notifications
Configuration
// in app.js
modules: {
'apostrophe-external-notifications': {
// OPTIONAL: an alias to make it easier to send your own notifications,
// see example below
alias: 'external',
platforms: {
slack: {
// See below for a more nuanced way to do this
channel: [ '#apostrophe-edits' ],
webhooks: {
'#apostrophe-edits': 'https://hooks.slack.com/services/GO/GET-YOUR-OWN'
}
}
}
}
}
To set this up in Slack, you need to register a Slack "app" here. After copying that information, click "Incoming Webhooks," then be sure to turn them on. Now click "Add New Webhook to Workspace" and select the desired channel. Repeat for each channel you wish to notify. Finally, copy and paste the resulting webhook URLs into the
webhooks
configuration as shown above.
Sending different events to different channels
The simple configuration above sends everything to the #apostrophe-edits
channel in Slack. You can also break down which events go to which channels:
modules: {
'apostrophe-external-notifications': {
alias: 'external',
platforms: {
slack: {
events: {
'apostrophe-workflow:afterCommit': '#apostrophe-commits',
'apostrophe-workflow:afterExport': '#apostrophe-exports',
'apostrophe-workflow:afterForceExport': '#apostrophe-exports'
},
webhooks: {
'#apostrophe-commits': 'https://hooks.slack.com/services/GO/GET-YOUR-OWN-1',
'#apostrophe-exports': 'https://hooks.slack.com/services/GO/GET-YOUR-OWN-2'
}
}
}
}
}
If you do not configure the shared channel
option, then only the events you individually configure are sent to Slack at all. You may also do it both ways.
Anywhere you see channels configured above, you can specify either an array of channels or a single channel.
If you configure more than one channel, you must also create and paste in the "webhook" URLs for each of them.
Limitations
There must be an Apostrophe promise event associated with what you want notifications for, and an external notification handler must be registered for that event. apostrophe-external-notifications
has handlers for some popular cases, but not all.
Built-in event listeners: what you can get without writing any code
Currently the following event handlers have listeners built into this module:
apostrophe-workflow:afterCommit
apostrophe-workflow:afterExport
apostrophe-workflow:afterForceExport
More event handlers are coming. In the meantime, you can add support for more events yourself, as shown below. We suggest doing so as a PR on the module in question so that the community benefits and you are aware when we add a handler that would otherwise duplicate yours.
Adding support for more events
Here's how you might add support for the afterCommit
event, if we didn't already have it. This code assumes you gave the module an alias in your project, as seen above.
self.apos.external.notifyOn('apostrophe-workflow:afterCommit', (req, commit) =>
[ '{user} committed the {type} {title} which has these tags: {string}.', commit.from, commit.from, commit.from.tags ]
);
"What's going on in this code?" apostrophe-workflow:afterCommit
is the event we want to listen for. (req, commit)
are the arguments that the afterCommit
event provides. We then return an array containing a template string, and arguments to replace parts of the template string. The template string can contain the following optional placeholders:
{user}
displays the current user's name, or falls back gracefully if there is no user. Powered by thereq
argument from the event, so we do not need to pass anything else. Not all events havereq
. Ifreq
is not present or contains no usernameAnonymous
is sent.{type}
displays the type of a document in a user-friendly way, or falls back to thetype
property. Expects a matchingdoc
argument as shown above. (Thecommit
object emitted byafterCommit
has afrom
property containing the doc that was committed.){title}
displays thetitle
a document in a user-friendly way, or falls back to theslug
property. Expects a matchingdoc
argument. (Thecommit
object emitted byafterCommit
has afrom
property containing the doc that was committed.){string}
simply expects and sends a string argument. If it receives an array argument, it will send it as a comma-separted string, with spaces.
While you could do everything with
{string}
, the other placeholders save time and prevent frequent causes of crashing bugs due to missing sanity checks.
Adding support for your own events in a published npm module
Thanks for doing that! Follow the above technique. However, in a public npm module, you MUST NOT assume that apostrophe-external-notifications
has a handy alias (do NOT write apos.external
). You also should NOT assume that the module is present at all. Instead, write:
const external = self.apos.modules['apostrophe-external-notifications'];
if (external) {
external.notifyOn(/* ... as seen above */);
}
Adding support for more platforms
Support for Slack ships with this module by default. You can add handlers for other platforms.
Here is a simplified Slack platform handler:
const rp = require('request-promise');
self.apos.externals.addPlatform('slack', async (req, options, channels, message) => {
for (const channel of channels) {
await rp({
method: 'POST',
uri: options.webhooks[channel],
form: {
text: message.formatted
}
});
}
});
The above example assumes you gave the module the alias
externals
. If you want to ship support for a platform as an npm module, refer to our module asself.apos.modules['apostrophe-externals']
to be safe.
Note that req
may be undefined in cases where an event is global and not concerned with an individual request. req
is provided in case you want to handle the message differently depending on the sender's identity. Here we do not.
channels
contains the array of channel names the event should be sent to. It may be empty and you should do nothing if it is empty, unless channels are not a relevant concept for your platform. If you don't care about channels, you may wish to look at message.event
, which contains the original ApostropheCMS promise event name.
message.formatted
contains the message to be sent, as a string. Placeholders have already been resolved, the message is complete and ready to send.
Although our platform handler function is
async
andawait
s each channel's message delivery to Slack, for the sake of performanceapostrophe-external-notifications
will not wait for the handler to finish before allowing the original Apostrophe event handler to return. However, for the sake of consistency the module does guarantee that notifications sent for a specificreq
will be delivered in order relative to their peers. Those with noreq
are also sent in order.