From 65aa1628d33a9f5481bde8dcf8a8018e28474584 Mon Sep 17 00:00:00 2001 From: Taylor Sampson Date: Sun, 11 Oct 2026 20:48:47 -0500 Subject: [PATCH 1/2] Fix webhook API docs to match server behavior (GG-1303) - A webhook created via the API only responds to the events passed in `events`; it does not default to all events. - Drop `include_received_email` from the documented request and response; passing `subscriber.received_email` in `events` replaces it. - Reword the `subscriber.received_email` volume note. - Add the JSON Content-Type header to the remaining curl examples that send a JSON body (webhook create, workflow trigger create/update); the API returns 415 for create/update requests without it. Co-Authored-By: Claude Opus 5.5 --- source/includes/rest/_webhook_events.md | 4 +++- source/includes/rest/_webhooks.md | 19 +++++-------------- source/includes/rest/_workflows.md | 2 ++ 3 files changed, 10 insertions(+), 15 deletions(-) diff --git a/source/includes/rest/_webhook_events.md b/source/includes/rest/_webhook_events.md index bb7a63d8232..8ab67f7f50a 100644 --- a/source/includes/rest/_webhook_events.md +++ b/source/includes/rest/_webhook_events.md @@ -15,6 +15,8 @@ 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. +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. In addition, you will be notified and your webhook will be temporarily disabled if its endpoint generates any other error for 3 days. @@ -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 Setting up above. +Note that this event can have extremely high volume. Only use it if necessary and ensure your server can handle the traffic. ## subscriber.opened_email diff --git a/source/includes/rest/_webhooks.md b/source/includes/rest/_webhooks.md index 6970cc63ce9..7a7a17cb3fc 100644 --- a/source/includes/rest/_webhooks.md +++ b/source/includes/rest/_webhooks.md @@ -8,7 +8,6 @@ "href": "https://api.getdrip.com/v2/9999999/webhooks/77777", "post_url": "http://www.mysite.com/my-webhook-endpoint", "version": "1", - "include_received_email": false, "events": [ "subscriber.created", "subscriber.subscribed_to_campaign" @@ -56,10 +55,6 @@ version The webhook version. The current stable version is 2. - - include_received_email - Returns true if a notification is sent whenever a subscriber receives an email. - created_at A timestamp representing when the webhook record was first created. @@ -197,6 +192,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 +216,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/receieve" events = [ "subscriber.created", "subscriber.subscribed_to_campaign" ] -response = client.create_webhook(post_url, include_received_email, events) +# The second argument is a legacy flag; add "subscriber.received_email" to events instead. +response = client.create_webhook(post_url, false, events) if response.success? puts response.body["webhooks"] @@ -267,7 +263,6 @@ client.createWebhook(payload) "href": "https://api.getdrip.com/v2/9999999/webhooks/77777", "post_url": "http://www.example.com/api/v2/form", "version": "1", - "include_received_email": false, "events": [ "subscriber.created", "subscriber.subscribed_to_campaign" @@ -298,13 +293,9 @@ client.createWebhook(payload) post_url The url that the webhook will post to. - - include_received_email - Optional. A Boolean specifying whether we should send a notification whenever a subscriber receives an email. Defaults to false. - events - Optional. An Array specifiying which events we should send notifications for. Eligible events can be found in the webhooks documentation. By default, we will send notifications for all events except subscrber.received_email. + An Array specifying which events we should send notifications for. Eligible events can be found in the webhooks documentation. The webhook only sends notifications for the events listed here; a webhook created without any events sends none. diff --git a/source/includes/rest/_workflows.md b/source/includes/rest/_workflows.md index 70030c15eac..33664efc1c0 100644 --- a/source/includes/rest/_workflows.md +++ b/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 From 4f50d1172c6e4202389911a22dfacfd543d9fef1 Mon Sep 17 00:00:00 2001 From: Taylor Sampson Date: Sun, 11 Oct 2026 22:08:26 -0500 Subject: [PATCH 2/2] Address verification findings (GG-1303) Restore the deprecated include_received_email argument and response field, mark events as optional, fix response JSON (integer version, trailing comma), and describe the current webhook settings UI. Co-Authored-By: Claude Opus 5.5 --- source/includes/rest/_webhook_events.md | 18 +++++++++--------- source/includes/rest/_webhooks.md | 24 +++++++++++++++++------- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/source/includes/rest/_webhook_events.md b/source/includes/rest/_webhook_events.md index 8ab67f7f50a..31efdff28af 100644 --- a/source/includes/rest/_webhook_events.md +++ b/source/includes/rest/_webhook_events.md @@ -8,12 +8,12 @@ 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)). @@ -37,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, @@ -64,7 +64,7 @@ An example of the fields you can expect when you see `"subscriber": { ... }` is event - The webhook notification's event name. For example, subscrber.received_email. + The webhook notification's event name. For example, subscriber.received_email. data @@ -408,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 this event can have extremely high volume. Only use it if necessary and ensure your server can handle the traffic. +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 Setting up. ## subscriber.opened_email @@ -598,7 +598,7 @@ only fires when lead scoring is enabled for your account. "account_id": "9999999", "subscriber": { ... }, "properties": { - "action": "Signed up for a trial" + "action": "Signed up for a trial", "plan": "rock-star", "amount": 2999 } diff --git a/source/includes/rest/_webhooks.md b/source/includes/rest/_webhooks.md index 7a7a17cb3fc..9d9a16fe78f 100644 --- a/source/includes/rest/_webhooks.md +++ b/source/includes/rest/_webhooks.md @@ -7,14 +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" } } ``` @@ -62,6 +63,10 @@ events An array specifying which events are enabled for webhook notifications. + + + include_received_email + Read-only. Returns true if events includes subscriber.received_email. Webhooks set to "All Events" in the UI return false even though they receive this event. links @@ -216,13 +221,13 @@ client = Drip::Client.new do |c| c.account_id = "YOUR_ACCOUNT_ID" end -post_url = "https://www.mylistener.com/receieve" +post_url = "https://www.mylistener.com/receive" events = [ "subscriber.created", "subscriber.subscribed_to_campaign" ] -# The second argument is a legacy flag; add "subscriber.received_email" to events instead. +# 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? @@ -262,14 +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" } }] } @@ -295,7 +301,11 @@ client.createWebhook(payload) events - An Array specifying which events we should send notifications for. Eligible events can be found in the webhooks documentation. The webhook only sends notifications for the events listed here; a webhook created without any events sends none. + Optional. An Array specifying which events we should send notifications for. Eligible events can be found in the webhooks documentation. The webhook only sends notifications for the events listed here; a webhook created without any events sends none. Unrecognized event names return a 422. + + + include_received_email + Deprecated. Optional. A Boolean. Setting it to true is the same as adding subscriber.received_email to events. Defaults to false.