Standardized action verbs for Webhooks (#183)

* Updated webhooks lib and tests

* Updated webhooks doc and examples

* updated tests for payloads and cloneDeep

* validates required parameters and jsdocs to webhooks wrapper

* update docs for webhooks

* updated docs, tests, and examples

* eslint fixes

* fix merge conflicts

docs/resources/webhooks.md

@@ -2,56 +2,21 @@
 
 This library provides easy access to the [Webhooks](https://developers.sparkpost.com/api/webhooks) Resource.
 
-## Methods
-* **all([options, callback]) &rarr; `{Promise}`**<br />
-  List currently extant webhooks.
-  * `options.timezone` - `String` Standard timezone identification Default: `UTC`
-  * `callback` - executed after task is completed if provided*
-    * standard `callback(err, data)`
-    * `err` - any error that occurred
-    * `data` - full response from request client
-* **describe(options[, callback]) &rarr; `{Promise}`**<br />
-  Retrieve details about a specified webhook by its id
-  * `options.id` - the id of the webhook you want to describe **required**
-  * `options.timezone` - `String` Standard timezone identification Default: `UTC`
-  * `callback` - see all function
-* **create(webhook[, callback]) &rarr; `{Promise}`**<br />
-  Create a new webhook
-  * `webhook` - an object of [webhook attributes](https://developers.sparkpost.com/api/webhooks#header-webhooks-object-properties) **required**
-  * `callback` - see all function
-* **update(webhook[, callback]) &rarr; `{Promise}`**<br />
-  Update an existing webhook
-  * `webhook` - an object of [webhook attributes](https://developers.sparkpost.com/api/webhooks#header-webhooks-object-properties) **required**
-  * `callback` - see all function
-* **delete(id[, callback]) &rarr; `{Promise}`**<br />
-  Delete an existing webhook
-  * `id` - the id of the webhook you want to delete **required**
-  * `callback` - see all function
-* **validate(options[, callback]) &rarr; `{Promise}`**<br />
-  Sends an example message event batch from the Webhook API to the target URL
-  * `options.id` - the id of the webhook you want to validate **required**
-  * `options.message` - sample object to send to the target URL **required**
-  * `callback` - see all function
-* **getBatchStatus(options[, callback]) &rarr; `{Promise}`**<br />
-  Sends an example message event batch from the Webhook API to the target URL
-  * `options.id` - the id of the webhook you want to get status on **required**
-  * `options.limit` - `number` maximum number of results to return Default: `1000`
-  * `callback` - see all function
-* **getDocumentation([callback]) &rarr; `{Promise}`**<br />
-  Lists descriptions of the events, event types, and event fields that could be included in a Webhooks post to your target URL.
-  * `callback` - see all function
-* **getSamples(options[, callback]) &rarr; `{Promise}`**<br />
-  List an example of the event data that will be posted by a Webhook for the specified events.
-  * `options.events` - `String` event types for which to get a sample payload Defaults to all event types
-  * `callback` - see all function
+*Note: All methods return promises and accept an optional last argument callback. [Read about how we handle callbacks and promises](/docs/async.md).*
 
-*callback is optional because all methods return a Promise.
+## Methods
+* **list([options])**<br />
+  Lists all webhooks.
+  * `options.timezone` - the timezone to use for the `last_successful` and `last_failure` properties | Default: `UTC`
 
-## Examples
+* **get(id[, options])**<br />
+  Get a single webhook by ID.
+  * `id` - the id of the webhook to get **required**
+  * `options.timezone` - the timezone to use for the `last_successful` and `last_failure` properties | Default: `UTC`
 
-```javascript
-var SparkPost = require('sparkpost')
-  , client = new SparkPost('YOUR_API_KEY');
+* **create(webhook)**<br />
+  Create a new webhook.
+  * `webhook` - a hash of [webhook attributes](https://developers.sparkpost.com/api/webhooks#header-webhooks-object-properties) **required**
 
 client.webhooks.all()
   .then(data => {
@@ -63,17 +28,30 @@ client.webhooks.all()
     console.log(err);
   });
 
-// Using a callback
-client.webhooks.all(function(err, data) {
-  if(err) {
-    console.log('Whoops! Something went wrong');
-    console.log(err);
-  } else {
-    console.log('Congrats you can use our client library!');
-    console.log(data);
-  }
-});
+* **update(id, webhook)**<br />
+  Update an existing webhook.
+  * `id` - the id of the webhook to update **required**
+  * `webhook` - a hash of [webhook attributes](https://developers.sparkpost.com/api/webhooks#header-webhooks-object-properties) **required**
+* **delete(id)**<br />
+  Delete an existing webhook.
+  * `id` - the id of the webhook to delete **required**
+
+* **validate(id, options)**<br />
+  Sends an example message event batch from the Webhook API to the target URL.
+  * `id` - the id of the webhook to validate **required**
+  * `options.message` - the message (payload) to send to the webhook consumer **required**
+
+* **getBatchStatus(id[, options])**<br />
+  Gets recent status information about a webhook.
+  * `id` - the id of the webhook **required**
+  * `options.limit` - maximum number of results to return | Default: `1000`
+
+* **getDocumentation()**<br />
+  Lists descriptions of the events, event types, and event fields that could be included in a webhooks post to your target URL.
+
+* **getSamples(options)**<br />
+  Lists examples of the event data that will be posted to a webhook consumer.
+  * `options.events` - [event types](https://support.sparkpost.com/customer/portal/articles/1976204) for which to get a sample payload | Default: all event types returned
 
-```
 
-Check out all the examples provided [here](/examples/webhooks).
+Visit our examples section to see all of [our webhooks resource examples](/examples/webhooks).

examples/webhooks/create_webhook.js → examples/webhooks/create.js

@@ -15,6 +15,7 @@ var key = 'YOURAPIKEY'
     ]
   };
 
+// Promise
 client.webhooks.create(webhook)
   .then(data => {
     console.log('Congrats you can use our client library!');
@@ -25,7 +26,7 @@ client.webhooks.create(webhook)
     console.log(err);
   });
 
-// Using a callback
+// Callback
 client.webhooks.create(webhook, function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');

examples/webhooks/delete_webhook.js → examples/webhooks/delete.js

@@ -4,6 +4,7 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key);
 
+// Promise
 client.webhooks.delete('TEST_WEBHOOK_UUID')
   .then(data => {
     console.log('Congrats you can use our client library!');
@@ -14,7 +15,7 @@ client.webhooks.delete('TEST_WEBHOOK_UUID')
     console.log(err);
   });
 
-// Using a callback
+// Callback
 client.webhooks.delete('TEST_WEBHOOK_UUID', function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');

examples/webhooks/describe_webhook.js → examples/webhooks/get.js

@@ -4,11 +4,11 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key)
   , options = {
-    id: 'TEST_WEBHOOK_UUID',
     timezone: 'America/New_York'
   };
 
-client.webhooks.describe(options)
+// Promise
+client.webhooks.get('TEST_WEBHOOK_UUID', options)
   .then(data => {
     console.log('Congrats you can use our client library!');
     console.log(data);
@@ -18,8 +18,8 @@ client.webhooks.describe(options)
     console.log(err);
   });
 
-// Using a callback
-client.webhooks.describe(options, function(err, data) {
+// Callback
+client.webhooks.get('TEST_WEBHOOK_UUID', options, function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');
     console.log(err);

examples/webhooks/getBatchStatus.js

@@ -4,11 +4,11 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key)
   , options = {
-    id: 'TEST_WEBHOOK_UUID',
     limit: 1000
   };
 
-client.webhooks.getBatchStatus(options)
+// Promise
+client.webhooks.getBatchStatus('TEST_WEBHOOK_UUID', options)
   .then(data => {
     console.log('Congrats you can use our client library!');
     console.log(data);
@@ -18,8 +18,8 @@ client.webhooks.getBatchStatus(options)
     console.log(err);
   });
 
-// Using a callback
-client.webhooks.getBatchStatus(options, function(err, data) {
+// Callback
+client.webhooks.getBatchStatus('TEST_WEBHOOK_UUID', options, function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');
     console.log(err);

examples/webhooks/getDocumentation.js

@@ -4,6 +4,7 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key);
 
+// Promise
 client.webhooks.getDocumentation()
   .then(data => {
     console.log('Congrats you can use our client library!');
@@ -14,7 +15,7 @@ client.webhooks.getDocumentation()
     console.log(err);
   });
 
-// Using a callback
+// Callback
 client.webhooks.getDocumentation(function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');

examples/webhooks/getSamples.js

@@ -7,6 +7,7 @@ var key = 'YOURAPIKEY'
     events: 'bounce'
   };
 
+// Promise
 client.webhooks.getSamples(options)
   .then(data => {
     console.log('Congrats you can use our client library!');
@@ -17,7 +18,7 @@ client.webhooks.getSamples(options)
     console.log(err);
   });
 
-// Using a callback
+// Callback
 client.webhooks.getSamples(options, function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');

examples/webhooks/get_all_webhooks.js → examples/webhooks/list.js

@@ -4,7 +4,8 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key);
 
-client.webhooks.all()
+// Promise
+client.webhooks.list()
   .then(data => {
     console.log('Congrats you can use our client library!');
     console.log(data);
@@ -14,8 +15,8 @@ client.webhooks.all()
     console.log(err);
   });
 
-// Using a callback
-client.webhooks.all(function(err, data) {
+// Callback
+client.webhooks.list(function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');
     console.log(err);

examples/webhooks/update_webhook.js → examples/webhooks/update.js

@@ -4,15 +4,15 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key)
   , webhook = {
-    id: 'TEST_WEBHOOK_UUID',
     name: 'Renamed Test Webhook',
     events: [
       'policy_rejection',
       'delay'
     ]
   };
 
-client.webhooks.update(webhook)
+// Promise
+client.webhooks.update('TEST_WEBHOOK_UUID', webhook)
   .then(data => {
     console.log('Congrats you can use our client library!');
     console.log(data);
@@ -22,8 +22,8 @@ client.webhooks.update(webhook)
     console.log(err);
   });
 
-// Using a callback
-client.webhooks.update(webhook, function(err, data) {
+// Callback
+client.webhooks.update('TEST_WEBHOOK_UUID', webhook, function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');
     console.log(err);

examples/webhooks/validate_webhook.js → examples/webhooks/validate.js

@@ -4,13 +4,13 @@ var key = 'YOURAPIKEY'
   , SparkPost = require('sparkpost')
   , client = new SparkPost(key)
   , options = {
-    id: 'TEST_WEBHOOK_UUID',
     message: {
       msys: {}
     }
   };
 
-client.webhooks.validate(options)
+// Promise
+client.webhooks.validate('TEST_WEBHOOK_UUID', options)
   .then(data => {
     console.log('Congrats you can use our client library!');
     console.log(data);
@@ -20,8 +20,8 @@ client.webhooks.validate(options)
     console.log(err);
   });
 
-// Using a callback
-client.webhooks.validate(options, function(err, data) {
+// Callback
+client.webhooks.validate('TEST_WEBHOOK_UUID', options, function(err, data) {
   if (err) {
     console.log('Whoops! Something went wrong');
     console.log(err);