[ENG-3777] add docs on gong subscribe

src/customer-guides/gong.mdx

@@ -0,0 +1,46 @@
+---
+title: Gong
+---
+
+## Checklist before you start
+
+Confirm the following:
+
+- You are a Gong **Technical Administrator** (the role required to create automation rules and configure outbound webhooks).
+- Your developer has provided you with a **webhook URL** in this format:
+
+  ```
+  https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
+  ```
+
+## Set up webhooks for real-time updates (Subscribe Actions)
+
+To send `call.created` events to your developer's application, you'll create an **automation rule** in Gong that fires a webhook each time a call is processed.
+
+1. Sign in to Gong and open **Admin Settings** in the left sidebar.
+   <img src="/images/customer-guides/gong/admin-settings.png" />
+2. In the left sidebar, navigate to **Automation rules**.
+   <img src="/images/customer-guides/gong/automation-rules.png" />
+3. Click **Add rule**.
+   <img src="/images/customer-guides/gong/add-rule.png" />
+4. (Optional) Add any filters you'd like to apply — for example, restrict the rule to specific participants. Leave the filters empty to send every new call.
+   <img src="/images/customer-guides/gong/filters.png" />
+5. Paste the webhook URL your developer gave you into the **Enter URL** field.
+   <img src="/images/customer-guides/gong/webhook-url.png" />
+6. Give the rule a descriptive name and toggle **"Rule Status"** to **Enabled**. 
+   <img src="/images/customer-guides/gong/rule-status.png" />
+7. (Optional) Send a test webhook and click Save.
+   <img src="/images/customer-guides/gong/test.png" />
+
+## When to expect the webhook to fire
+
+Gong fires the `call.created` webhook after a call has finished processing and appears in your Gong call library, which can take **several hours** after the call ends. You will not see events arrive immediately after a call wraps up — this is expected.
+
+The screenshot below shows where a processed call shows up. Once a call reaches this state, the webhook has been (or will shortly be) sent.
+
+<img src="/images/customer-guides/gong/processed-call.png" />
+
+## For official setup details, see:
+
+- [Gong Automation Rules overview](https://help.gong.io/docs/introduction-to-automation-rules)
+- [Send a webhook from an automation rule](https://help.gong.io/docs/create-a-webhook-rule)

src/docs.json

@@ -254,17 +254,18 @@
                 "group": "Customer guides",
                 "pages": [
                   "customer-guides/overview",
+                  "customer-guides/update-connection",
                   "customer-guides/bigquery",
+                  "customer-guides/gong",
                   "customer-guides/google-workspace-delegation",
-                  "customer-guides/salesforce",
-                  "customer-guides/salesforce-jwt",
-                  "customer-guides/loxo",
-                  "customer-guides/hubspot",
                   "customer-guides/housecallPro",
+                  "customer-guides/hubspot",
+                  "customer-guides/loxo",
                   "customer-guides/marketo",
-                  "customer-guides/snowflake",
                   "customer-guides/netsuite",
-                  "customer-guides/update-connection"
+                  "customer-guides/salesforce",
+                  "customer-guides/salesforce-jwt",
+                  "customer-guides/snowflake"
                 ]
               },
               "dev-and-prod-environments",

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. |

src/provider-guides/gong.mdx

@@ -13,19 +13,25 @@ updatedAt: "Fri Jul 19 2024 21:54:48 GMT+0000 (Coordinated Universal Time)"
 This connector supports:
 - [Proxy Actions](/proxy-actions), using the base URL `https://api.gong.io`.
 - [Read Actions](/read-actions)
+- [Subscribe Actions](/subscribe-actions). Please note that [special set up](#set-up-subscribe-actions) is needed for Gong.
 
 ### Supported Objects
 
-The Gong connector supports **reading** from the following objects:
-- Users (full read only)
-- Workspaces (full read only)
-- Flows (full read only)
-- Calls and Transcripts (incremental read in private preview, contact [email protected]).
+| Object      | Read                                 | Write | Subscribe                |
+| ----------- | ------------------------------------ | ----- | ------------------------ |
+| Users       | ✓ (full read only)                   |       |                          |
+| Workspaces  | ✓ (full read only)                   |       |                          |
+| Flows       | ✓ (full read only)                   |       |                          |
+| Calls       | ✓ (incremental in private preview¹)  | ✓     | ✓ (`call.created` only)  |
+| Transcripts | ✓ (incremental in private preview¹)  |       |                          |
 
-The Gong connector supports **writing** to the following objects:
-- Calls
+¹ Contact [email protected] to enable incremental read for Calls and Transcripts.
 
-> **Note:** Due to Gong's processing time. `Calls` may not be available through Read Actions until up to an hour after a call ends, and `Transcripts` may not be available until up to 24 hours after a call ends.
+<Note>
+  **Gong processing latency.** Gong takes time to process recordings before they become available, which delays both Read Actions and Subscribe webhooks:
+  - **Calls** are available through through Read and Subscribe Actions after they have finished processing in Gong, which may take up to **1 hour** after a call ends.
+  - **Transcripts** may not be available for up to **24 hours** after a call ends.
+</Note>
 
 ### Example Integration
 
@@ -71,3 +77,35 @@ Learn more about the Gong Partnership process [here](https://help.gong.io/docs/h
 
 
 8. Click **Save Changes**.
+
+## Set up Subscribe Actions
+
+1. **Define the subscribe action** in your `amp.yaml` and deploy it with the [amp CLI](/cli/overview). Gong only supports the `call.created` event, so the `calls` object should subscribe to `createEvent` only.
+
+   ```yaml
+   specVersion: 1.0.0
+   integrations:
+     - name: subscribeToGong
+       provider: gong
+       subscribe:
+         objects:
+           - objectName: calls
+             destination: gongWebhook
+             inheritFieldsAndMapping: true
+             createEvent:
+               enabled: always
+       read: 
+         objects:
+           - objectName: calls
+             destination: gongWebhook
+             requiredFields:
+               ...
+   ```
+
+2. **Construct a webhook URL for your customer** in this format:
+
+   ```
+   https://subscribe-webhook.withampersand.com/v1/projects/PROJECT_ID/integrations/INTEGRATION_ID/installations/INSTALLATION_ID
+   ```
+
+3. **Share the [Gong customer guide](/customer-guides/gong)** with your customer along with the webhook URL from Step 2. Your customer will create an automation rule in Gong that fires a webhook when a new call is created.

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.