[GG-1303] Fix webhook API docs to match how the server behaves

source/includes/rest/_webhook_events.md

@@ -8,12 +8,14 @@ you'll want to use webhooks.
 
 ## Setting Up
 
-Adding a webhook URL is dead simple. Head over the [Webhooks](https://www.getdrip.com/webhooks)
-settings page, enter your URL, and hit "Create Webhook". That's it!
+To add a webhook, head over to the [Webhooks](https://www.getdrip.com/webhooks)
+settings page, click "New webhook", and enter your URL. Choose "All Events" or
+"Select Events", then click "Save".
 
-Because of the potential for high volume, we will not send notifications for
-`subscriber.received_email` events by default. To receive a post every time a subscriber
-receives an email, enable these events using the checkbox on the webhook's settings.
+"All Events" includes `subscriber.received_email`, which can be very high volume.
+To avoid it, choose "Select Events" and leave "Received an email" unticked.
+
+Webhooks created through the API only send notifications for the events listed in `events` (see [Create a new webhook](#create-a-new-webhook)).
 
 Please note that some webhook endpoints may implement rate limiting, especially for entry-level or free accounts.
 We will attempt to re-send webhooks for up to 3 days if they are rate limited.
@@ -35,7 +37,7 @@ In addition, you will be notified and your webhook will be temporarily disabled
   "tags": ["Customer", "SEO"],
   "time_zone": "America/Los_Angeles",
   "utc_offset": -440,
-  "created_at": "2013-06-21T10:31:58Z"
+  "created_at": "2013-06-21T10:31:58Z",
   "ip_address": "123.123.123.123",
   "user_agent": "Mozilla/5.0",
   "lifetime_value": 2000,
@@ -62,7 +64,7 @@ An example of the fields you can expect when you see `"subscriber": { ... }` is
   <tbody>
     <tr>
       <td><code>event</code></td>
-      <td>The webhook notification's event name. For example, <code>subscrber.received_email</code>.</td>
+      <td>The webhook notification's event name. For example, <code>subscriber.received_email</code>.</td>
     </tr>
     <tr>
       <td><code>data</code></td>
@@ -406,7 +408,7 @@ This event is triggered when a subscriber's time zone is updated.
 
 This event is triggered when a subscriber receives an email.
 
-Note that because of their potentially high volume, notifications for this event are optional. See <a href="#setting-up">Setting up</a> above.
+Note that this event can have extremely high volume. Only use it if necessary and ensure your server can handle the traffic. It is only sent if this event is selected on the webhook; see <a href="#setting-up">Setting up</a>.
 
 ## subscriber.opened_email
 
@@ -596,7 +598,7 @@ only fires when lead scoring is enabled for your account.</strong>
     "account_id": "9999999",
     "subscriber": { ... },
     "properties": {
-      "action": "Signed up for a trial"
+      "action": "Signed up for a trial",
       "plan": "rock-star",
       "amount": 2999
     }

source/includes/rest/_webhooks.md

@@ -7,15 +7,15 @@
   "id": "77777",
   "href": "https://api.getdrip.com/v2/9999999/webhooks/77777",
   "post_url": "http://www.mysite.com/my-webhook-endpoint",
-  "version": "1",
+  "version": 2,
   "include_received_email": false,
   "events": [
     "subscriber.created",
     "subscriber.subscribed_to_campaign"
   ],
   "created_at": "2013-06-21T10:31:58Z",
   "links": {
-    "account": "9999999",
+    "account": "9999999"
   }
 }
 ```
@@ -56,17 +56,17 @@
       <td><code>version</code></td>
       <td>The webhook version. The current stable version is 2.</td>
     </tr>
-    <tr>
-      <td><code>include_received_email</code></td>
-      <td>Returns true if a notification is sent whenever a subscriber receives an email.</td>
-    </tr>
     <tr>
       <td><code>created_at</code></td>
       <td>A timestamp representing when the webhook record was first created.</td>
     </tr>
      <tr>
       <td><code>events</code></td>
       <td>An array specifying which events are enabled for webhook notifications.</td>
+    </tr>
+     <tr>
+      <td><code>include_received_email</code></td>
+      <td>Read-only. Returns true if <code>events</code> includes <code>subscriber.received_email</code>. Webhooks set to "All Events" in the UI return false even though they receive this event.</td>
     </tr>
      <tr>
       <td><code>links</code></td>
@@ -197,6 +197,7 @@ None.
 
 ```shell
 curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/webhooks" \
+  -H "Content-Type: application/json" \
   -H 'User-Agent: Your App Name (www.yourapp.com)' \
   -u YOUR_API_KEY: \
   -d @- << EOF
@@ -220,14 +221,14 @@ client = Drip::Client.new do |c|
   c.account_id = "YOUR_ACCOUNT_ID"
 end
 
-pot_url = "https://www.mylistener.com/receieve"
-include_received_email = false
+post_url = "https://www.mylistener.com/receive"
 events = [
   "subscriber.created",
   "subscriber.subscribed_to_campaign"
 ]
 
-response = client.create_webhook(post_url, include_received_email, events)
+# The second argument (include_received_email) is legacy; passing true is the same as adding "subscriber.received_email" to events.
+response = client.create_webhook(post_url, false, events)
 
 if response.success?
   puts response.body["webhooks"]
@@ -266,15 +267,15 @@ client.createWebhook(payload)
     "id": "77777",
     "href": "https://api.getdrip.com/v2/9999999/webhooks/77777",
     "post_url": "http://www.example.com/api/v2/form",
-    "version": "1",
+    "version": 2,
     "include_received_email": false,
     "events": [
       "subscriber.created",
       "subscriber.subscribed_to_campaign"
     ],
     "created_at": "2013-06-21T10:31:58Z",
     "links": {
-      "account": "9999999",
+      "account": "9999999"
     }
   }]
 }
@@ -299,12 +300,12 @@ client.createWebhook(payload)
       <td>The url that the webhook will post to.</td>
     </tr>
     <tr>
-      <td><code>include_received_email</code></td>
-      <td>Optional. A Boolean specifying whether we should send a notification whenever a subscriber receives an email. Defaults to <code>false</code>.</td>
+      <td><code>events</code></td>
+      <td>Optional. An Array specifying which events we should send notifications for. Eligible events can be found in the <a href="#webhook-events">webhooks documentation</a>. The webhook only sends notifications for the events listed here; a webhook created without any events sends none. Unrecognized event names return a <code>422</code>.</td>
     </tr>
     <tr>
-      <td><code>events</code></td>
-      <td>Optional. An Array specifiying which events we should send notifications for. Eligible events can be found in the <a href="#webhook-events">webhooks documentation</a>. By default, we will send notifications for all events except <code>subscrber.received_email</code>.</td>
+      <td><code>include_received_email</code></td>
+      <td>Deprecated. Optional. A Boolean. Setting it to true is the same as adding <code>subscriber.received_email</code> to <code>events</code>. Defaults to <code>false</code>.</td>
     </tr>
   </tbody>
 </table>

source/includes/rest/_workflows.md

@@ -983,6 +983,7 @@ None.
 
 ```shell
 curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/triggers" \
+  -H "Content-Type: application/json" \
   -H 'User-Agent: Your App Name (www.yourapp.com)' \
   -u YOUR_API_KEY: \
   -d @- << EOF
@@ -1104,6 +1105,7 @@ client.createTrigger(workflowId, payload)
 
 ```shell
 curl -X PUT "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/triggers/TRIGGER_ID" \
+  -H "Content-Type: application/json" \
   -H 'User-Agent: Your App Name (www.yourapp.com)' \
   -u YOUR_API_KEY: \
   -d @- << EOF