amp-labs · laurenzlong · May 1, 2026 · Apr 27, 2026
diff --git a/src/manifest-reference.mdx b/src/manifest-reference.mdx
@@ -117,7 +117,7 @@ subscribe:
 Subscribe considerations
 
 - Check the specific [provider guide](/provider-guides/overview) to see which providers support subscribe actions. If subscribe actions isn't supported for a particular provider, you can still use read actions to get updated data every 10 minutes.
-- You must also have a read action specified for the object you wish to subscribe to.
+- A `read` block must always be defined alongside a `subscribe` block. Each subscribed object that uses `createEvent`, `updateEvent`, or `deleteEvent` must also have a matching object entry in the `read` block (with the same `objectName`) and set `inheritFieldsAndMapping: true`. Objects that only use `otherEvents` do not need their own entry in the `read` block.
 - Only one of `requiredWatchFields` or `watchFieldsAuto` should be provided for update events.
 - See [Subscribe Actions documentation](/subscribe-actions) for detailed implementation guidance.
 </Note>
@@ -232,7 +232,7 @@ Each object in the `objects` array defines a specific object type to subscribe t
 |-------|------|----------|-------------|
 | `objectName` | String | Yes | The [name of the object](#object-name) to subscribe to. Must match an object type supported by the provider. Case-sensitive. |
 | `destination` | String | Yes | The [webhook destination](#destination) for the event data. This determines where the event data will be sent. Must match a webhook configured in your Ampersand account. See [Destinations](/destinations) for setup. |
-| `inheritFieldsAndMapping` | Boolean | Yes | Whether to inherit field mappings from read configuration. For Salesforce, this must be set to `true`. |
+| `inheritFieldsAndMapping` | Boolean | Conditional | Whether to inherit field mappings from read configuration. Required and must be set to `true` when the object uses `createEvent`, `updateEvent`, or `deleteEvent`. Not required for objects that only use `otherEvents`. |
 | `createEvent` | Object | No | Configuration for create events. See [Event Configuration](#subscribe-action-events) below. |
 | `updateEvent` | Object | No | Configuration for update events. See [Event Configuration](#subscribe-action-events) below. |
 | `deleteEvent` | Object | No | Configuration for delete events. See [Event Configuration](#subscribe-action-events) below. |

diff --git a/src/provider-guides/housecallPro.mdx b/src/provider-guides/housecallPro.mdx
@@ -8,56 +8,56 @@ title: Housecall Pro
 
 This connector supports:
 
-- [Read Actions](/read-actions), including full historic backfill. Please note that incremental read is not supported for all objects.
+- [Read Actions](/read-actions), including full historic backfill. **Please note that incremental read is not supported for all objects.**
 - [Write Actions](/write-actions).
-- [Subscribe Actions](/subscribe-actions).
+- [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for Housecall Pro.
 - [Proxy Actions](/proxy-actions), using the base URL `https://api.housecallpro.com`.
 
-If your integration includes [Subscribe Actions](/subscribe-actions), customers need to enable webhooks in Housecall Pro and paste the webhook URL you provide. Share the [Housecall Pro customer guide](/customer-guides/housecallPro#2-enable-and-configure-webhooks) for those steps.
-
 ### Supported Objects
 
-The Housecall Pro connector supports the following objects.
-
-- [customers](https://docs.housecallpro.com/docs/housecall-public-api/042bd3bf861ae-get-customers) (read, subscribe, write; incremental read supported)
-- [employees](https://docs.housecallpro.com/docs/housecall-public-api/303ee235f23fa-get-employees) (read, subscribe)
-  <Note>
-    In Housecall Pro’s webhook UI, this event appears as pro.created, but the
-    actual payload uses employee.created.
-  </Note>
-- [estimates](https://docs.housecallpro.com/docs/housecall-public-api/e430ba3d520a0-get-estimates) (read, subscribe, write; incremental read supported)
-- [events](https://docs.housecallpro.com/docs/housecall-public-api/5f8b2b787f4ba-get-events) (read; incremental read supported)
-- [jobs](https://docs.housecallpro.com/docs/housecall-public-api/6c97704da8bf3-get-jobs) (read, subscribe, write; incremental read supported)
-- [job_fields/job_types](https://docs.housecallpro.com/docs/housecall-public-api/0c6fb36d5730d-get-job-types) (read, write)
-- [leads](https://docs.housecallpro.com/docs/housecall-public-api/278974bc87e32-get-leads) (read, subscribe, write)
-  <Note>
-    Delete events for lead are not reliable due to HouseCall Pro's platform
-    limitations.
-  </Note>
-- [lead_sources](https://docs.housecallpro.com/docs/housecall-public-api/7444a4f65ed77-get-lead-sources) (read, write)
-- [price_book/materials](https://docs.housecallpro.com/docs/housecall-public-api/e404d4b30ea0d-create-material) (write)
-- [price_book/material_categories](https://docs.housecallpro.com/docs/housecall-public-api/77aaf46f5b3db-get-material-categories) (read, write; incremental read supported)
-- [price_book/price_forms](https://docs.housecallpro.com/docs/housecall-public-api/e9b15f38e151b-get-price-forms) (read, write)
-- [price_book/services](https://docs.housecallpro.com/docs/housecall-public-api/b68be85878ece-get-price-book-services) (read)
-- [service_zones](https://docs.housecallpro.com/docs/housecall-public-api/38b31504822e9-get-service-zones) (read)
-- [routes](https://docs.housecallpro.com/docs/housecall-public-api/8d0d12e41a38b-get-routes) (read)
-- [tags](https://docs.housecallpro.com/docs/housecall-public-api/e8fa7b29f8a8b-get-tags) (read, write)
-- [invoices](https://docs.housecallpro.com/docs/housecall-public-api/65ce9f430d605-get-invoices) (read, subscribe)
-- [job.appointments](https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks#job-appointment-webhook-events) (subscribe only via [`otherEvents`](/subscribe-actions#other-events))
-  - **Example** `subscribe` fragment (for `job.appointments` only):
-
-    ```yaml
-    - objectName: job.appointments
-      destination: housecallProWebhook
-      otherEvents:
-        - job.appointment.scheduled
-        - job.appointment.rescheduled
-        - job.appointment.appointment_discarded
-        - job.appointment.appointment_pros_assigned
-        - job.appointment.appointment_pros_unassigned
-    ```
-
-    List Housecall Pro’s event strings exactly as they appear in webhooks. Standard events are not supported for this object. See [Other events](/subscribe-actions#other-events).
+| Object | Read | Write | Subscribe | Notes |
+| ------ | ---- | ----- | --------- | ----- |
+| [customers](https://docs.housecallpro.com/docs/housecall-public-api/042bd3bf861ae-get-customers) | ✓ (incremental) | ✓ | ✓ | |
+| [employees](https://docs.housecallpro.com/docs/housecall-public-api/303ee235f23fa-get-employees) | ✓ | | ✓ | ¹ |
+| [estimates](https://docs.housecallpro.com/docs/housecall-public-api/e430ba3d520a0-get-estimates) | ✓ (incremental) | ✓ | ✓ | |
+| [events](https://docs.housecallpro.com/docs/housecall-public-api/5f8b2b787f4ba-get-events) | ✓ (incremental) | | | |
+| [jobs](https://docs.housecallpro.com/docs/housecall-public-api/6c97704da8bf3-get-jobs) | ✓ (incremental) | ✓ | ✓ | |
+| [job_fields/job_types](https://docs.housecallpro.com/docs/housecall-public-api/0c6fb36d5730d-get-job-types) | ✓ | ✓ | | |
+| [leads](https://docs.housecallpro.com/docs/housecall-public-api/278974bc87e32-get-leads) | ✓ | ✓ | ✓ | ² |
+| [lead_sources](https://docs.housecallpro.com/docs/housecall-public-api/7444a4f65ed77-get-lead-sources) | ✓ | ✓ | | |
+| [price_book/materials](https://docs.housecallpro.com/docs/housecall-public-api/e404d4b30ea0d-create-material) | | ✓ | | |
+| [price_book/material_categories](https://docs.housecallpro.com/docs/housecall-public-api/77aaf46f5b3db-get-material-categories) | ✓ (incremental) | ✓ | | |
+| [price_book/price_forms](https://docs.housecallpro.com/docs/housecall-public-api/e9b15f38e151b-get-price-forms) | ✓ | ✓ | | |
+| [price_book/services](https://docs.housecallpro.com/docs/housecall-public-api/b68be85878ece-get-price-book-services) | ✓ | | | |
+| [service_zones](https://docs.housecallpro.com/docs/housecall-public-api/38b31504822e9-get-service-zones) | ✓ | | | |
+| [routes](https://docs.housecallpro.com/docs/housecall-public-api/8d0d12e41a38b-get-routes) | ✓ | | | |
+| [tags](https://docs.housecallpro.com/docs/housecall-public-api/e8fa7b29f8a8b-get-tags) | ✓ | ✓ | | |
+| [invoices](https://docs.housecallpro.com/docs/housecall-public-api/65ce9f430d605-get-invoices) | ✓ | | ✓ | |
+| [job.appointments](https://docs.housecallpro.com/docs/housecall-public-api/46e9e1be07621-webhooks#job-appointment-webhook-events) | | | ✓ | ³ |
+
+¹ Subscribe only via [`otherEvents`](/subscribe-actions#other-events). In Housecall Pro's webhook UI, this event appears as `pro.created`, but the actual payload uses `employee.created`. Example fragment:
+
+```yaml
+- objectName: employee
+  destination: housecallProWebhook
+  otherEvents:
+    - employee.created
+```
+
+² Delete events for `leads` are not reliable due to Housecall Pro platform limitations.
+
+³ Subscribe only via [`otherEvents`](/subscribe-actions#other-events). Standard events are not supported. Example fragment:
+
+```yaml
+- objectName: job.appointments
+  destination: housecallProWebhook
+  otherEvents:
+    - job.appointment.scheduled
+    - job.appointment.rescheduled
+    - job.appointment.appointment_discarded
+    - job.appointment.appointment_pros_assigned
+    - job.appointment.appointment_pros_unassigned
+```
 
 ### Example integration
 
@@ -91,3 +91,18 @@ To integrate with Housecall Pro:
   - If your integration has [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), you'll start getting webhook messages.
   - If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
   - If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.
+
+## Set up Subscribe Actions
+
+To receive subscribe events from Housecall Pro, the **customer** will enable webhooks in their Housecall Pro UI using a webhook URL you provide.
+
+The flow:
+
+1. **Define the subscribe action** in your `amp.yaml` and deploy it with the [amp CLI](/cli/overview).
+2. **Generate a webhook URL for each customer** in this format:
+
+   ```
+   https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
+   ```
+
+3. **Share the [Housecall Pro customer guide](/customer-guides/housecallPro#2-set-up-webhooks-for-real-time-updates-subscribe-actions)** with the customer and the webhook URL from Step 2. The customer will paste the webhook URL into the Housecall Pro UI and enable the events your integration subscribes to.
diff --git a/src/provider-guides/hubspot.mdx b/src/provider-guides/hubspot.mdx
@@ -9,7 +9,7 @@ title: "HubSpot"
 The Hubspot connector supports:
 
 - [Read Actions](/read-actions), including full historic backfill, incremental reads, and filters.
-- [Subscribe Actions](/subscribe-actions). Please note that [special set up](/subscribe-actions#special-set-up-for-hubspot) is needed for HubSpot.
+- [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for HubSpot.
 - [Write Actions](/write-actions), including Bulk Write and Delete.
 - [Proxy Actions](/proxy-actions), using the base URL `https://api.hubapi.com`.
 
@@ -241,6 +241,114 @@ To start integrating with HubSpot:
 - Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component
 - Start using the connector!
 
+## Set up Subscribe Actions
+
+<Note>
+  HubSpot subscribe actions cannot notify you of changes to custom fields. There is a workaround that requires additional set up, please contact support@withampersand.com for details.
+</Note>
+
+To enable HubSpot subscribe actions, you will need to:
+- Define the subscribe action in your `amp.yaml` file and then deploy it. See the [Subscribe Actions documentation](/subscribe-actions) for details.
+- Make modifications to the HubSpot app (see below).
+
+
+### New project apps
+
+If you are using a new project app (that was created with the HubSpot CLI), then follow the instructions below. If you don't have any apps yet, follow the instructions in [Method 1: New Project Apps](#method-1-new-project-apps) above to create one.
+
+#### Create webhooks-hsmeta.json file
+
+Go to the directory that contains your HubSpot app, and add a file called `your-project-name/src/app/webhooks/webhooks-hsmeta.json`. So your directory should end up like this:
+
+```
+/your-project-name
+  /src/app
+    /webhooks
+      webhooks-hsmeta.json
+    app-hsmeta.json
+  hsproject.json
+```
+
+Replace `targetUrl` in the example `webhooks-hsmeta.json` file below with the one that is for your integration. It should follow the format: 
+
+```
+"https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID"
+```
+  - Replace `PROJECT_ID` with your Ampersand project ID, which can be found in the Dashboard's [General Settings page](https://dashboard.withampersand.com/projects/_/settings).
+  - Replace `INTEGRATION_ID` with your integration's ID, which can be found in the Dashboard's [Home page](https://dashboard.withampersand.com/projects/_).
+
+You can also edit the file with the desired objects and events you want to subscribe to. You can refer to [HubSpot documentation](https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks#webhook-configuration) for the syntax of this file.
+
+Example `webhooks-hsmeta.json`:
+```
+{
+  "uid": "ampersand_subscribe_actions",
+  "type": "webhooks",
+  "config": {
+    "settings": {
+      "targetUrl": "SEE_INSTRUCTIONS_ABOVE",
+      "maxConcurrentRequests": 50
+    },
+    "subscriptions": {
+      "crmObjects": [
+        {
+          "subscriptionType": "object.creation",
+          "objectType": "contact",
+          "active": true
+        },
+        {
+          "subscriptionType": "object.propertyChange",
+          "objectType": "contact",
+          "propertyName": "firstname",
+          "active": true
+        },
+        {
+          "subscriptionType": "object.propertyChange",
+          "objectType": "contact",
+          "propertyName": "lastname",
+          "active": true
+        },
+        {
+          "subscriptionType": "object.deletion",
+          "objectType": "contact",
+          "active": true
+        }
+      ]
+    }
+  }
+}
+```
+
+#### Deploy changes to HubSpot
+
+Once you are done editing `webhooks-hsmeta.json`, deploy it using the following command:
+
+```
+hs project upload
+```
+
+### Legacy apps
+
+If you have a legacy app (that was created in the HubSpot UI), follow the instructions below.
+
+1.  Login to your HubSpot account. 
+2.  Go to the **Apps** section.
+3.  Select your connected app.
+5.  Click on **Webhooks**.
+6.  Enter the Target URL:
+  ```
+    https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID
+  ```
+  - Replace `PROJECT_ID` with your Ampersand project ID, which can be found in the Dashboard's [General Settings page](https://dashboard.withampersand.com/projects/_/settings).
+  - Replace `INTEGRATION_ID` with your integration's ID, which can be found in the Dashboard's [Home page](https://dashboard.withampersand.com/projects/_).
+
+7.  Click **Create Subscription**.
+8.  Select object types, event types, and properties.
+9.  Select the required checkboxes for all objects.
+10. Click **Activate**.
+
+![Subscribe actions HubSpot](/images/subscribeactions-hubspot.gif)
+
 ## Customer guide
 
 Share the [HubSpot customer guide](/customer-guides/hubspot) with your customers to help them use your integration.