Server to handle Contentful webhook HTTP requests
npm install contentful-webhook-server
Webhooks in Contentful notify you when content in your space has changed.
Contentful webhook server is a lightweight server to handle these notifications:
- handles incoming Contentful webhook HTTP requests
- emits events for all Contentful webhook topics to allow easy webhook handling
- supports username/password authentication
- supports all default node HTTP server options
``bash`
$ npm install contentful-webhook-server
`javascript
// Create webhook server
var server = require('contentful-webhook-server')({
path: '/',
username: 'user',
password: 'pass'
});
// Attach handlers to Contentful webhooks
server.on('ContentManagement.ContentType.publish', function(req){
console.log('A content type was published!');
});
// Start listening for requests on port 3000
server.listen(3000, function(){
console.log('Contentful webhook server running on port ' + 3000)
});
`
You can pass a configuration object when instantiating the server:
`javascript`
// Create webhook server
var server = require('contentful-webhook-server')({
path: '/',
username: 'user',
password: 'pass'
});
where:
- path: the path you want the server to listen on, default: '/'
- username: the username you expect the request to contain, default: ''
- password: the password you expect the request to contain, default: ''
So to start a server on localhost:3000 without authentication, you can:
`javascript
// Create server with default options
var server = require('contentful-webhook-server')();
// Start listening for requests on port 3000
server.listen(3000, function(){
console.log('Contentful webhook server running on port ' + 3000)
});
`
and to start a server on localhost:3000/webhooks with authentication, you can:
`javascript
// Create server with default options
var server = require('contentful-webhook-server')({
path: '/webhooks',
username: 'user',
password: 'pass'
});
// Start listening for requests on port 3000
server.listen(3000, function(){
console.log('Contentful webhook server running on port ' + 3000)
});
`
The server emits incoming Contentful webhook topics as event, so you can:
`javascript
server.on('ContentManagement.ContentType.publish', function(req){
console.log('A content type was published!');
});
server.on('ContentManagement.ContentType.unpublish', function(req){
console.log('A content type was unpublished!');
});
server.on('ContentManagement.Entry.publish', function(req){
console.log('An entry was published!');
});
server.on('ContentManagement.Entry.unpublish', function(req){
console.log('An entry was unpublished!');
});
server.on('ContentManagement.Asset.publish', function(req){
console.log('An asset was published!');
});
server.on('ContentManagement.Asset.unpublish', function(req){
console.log('An asset was unpublished!');
});
`
> This module does not make any assumptions about your application and does NOT attempt to parse or extract the contents of the request.
> Instead it passes the request to your handler(s) so you can process (or ignore) the contents of the incoming message from within your handler(s).
The server emits a special wildcard event too in case you want to listen to all events in one go:
`javascript
// Handler for all successful requests
// Is not emitted when an error occurs
server.on('ContentManagement.*', function(topic, req){
// topic is available as string
// => e.g. ContentManagement.Asset.unpublish
console.log('Request came in for: ' + topic);
});
`
> This event is only emitted on successful requests, not on errors
When an invalid request comes in, a ContentManagement.error event is emitted:
`javascript`
// Handle errors
server.on('ContentManagement.error', function(err, req){
console.log(err);
});
If you want to try out your server during development, you can simulate a request without credentials using cUrl:
`bash`
$ curl -X POST --header "X-Contentful-Topic: ContentManagement.Entry.publish" localhost:3000
and simulate requests with authentication like this:
`bash``
$ curl -X POST -u user:pass --header "X-Contentful-Topic: ContentManagement.Entry.publish" localhost:3000
To enable webhooks in your Contentful space, go to your space settings and fill in the options you specified in your server configuration:
As soon as you save the webhook in Contentful, your server will start receiving notifications.
A working example is included here.
MIT
- Added ability to mount as middleware
- Added working example
- Updated documentation
- Added authentication support
- Updated documentation
- Added unit tests
- Updated documentation
- Initial version