Recurly webhook server
Webhooks in Recurly notify you when content in your space has changed.
Recurly webhook server is a lightweight server to handle these notifications:
- handles incoming Recurly webhook HTTP requests
- emits events for all Recurly webhook topics to allow easy webhook handling
- supports username/password authentication
- supports all default node HTTP server options
Installation
$ npm install recurly-webhook-server
Quick example
// Create webhook servervar server = path: '/' username: 'user' password: 'pass'; // Attach handlers to Recurly webhooksserver; // Start listening for requests on port 3000server;
Configuration
You can pass a configuration object when instantiating the server:
// Create webhook servervar 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:
// Create server with default optionsvar server = ; // Start listening for requests on port 3000server;
and to start a server on localhost:3000/webhooks
with authentication, you can:
// Create server with default optionsvar server = path: '/webhooks' username: 'user' password: 'pass'; // Start listening for requests on port 3000server;
Handling incoming webhook requests
The server emits incoming Recurly webhook topics as event, so you can:
server; server; server; server; server; server; server; ...
This module does not make any assumptions about your application.
Incoming XML data is converted to JSON and passed to your handler(s) so you can process (or ignore) the contents of the incoming message from within your handler(s).
Special wildcard event
The server emits a special wildcard event too in case you want to listen to all events in one go:
// Handler for all successful requests// Is not emitted when an error occursserver;
This event is only emitted on successful requests, not on errors
Handling errors and invalid requests
When an invalid request comes in, a Recurly.error
event is emitted:
// Handle errorsserver;
Simulating a request using curl
If you want to try out your server during development, you can simulate a request without credentials using cUrl:
$ curl -X POST --data "[recurly-xml-data-here]" localhost:3000
and simulate requests with authentication like this:
$ curl -X POST -u user:pass --data "[recurly-xml-data-here]" localhost:3000
Enabling webhooks in Recurly
To enable webhooks in your Recurly account, go to your developer settings and fill in the options you specified in your server configuration:
As soon as you save the webhook in Recurly, your server will start receiving notifications.
Example
A working example is included here.
License
MIT