diff --git a/src/customer-guides/gong.mdx b/src/customer-guides/gong.mdx new file mode 100644 index 00000000..3b09ac97 --- /dev/null +++ b/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. + +2. In the left sidebar, navigate to **Automation rules**. + +3. Click **Add rule**. + +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. + +5. Paste the webhook URL your developer gave you into the **Enter URL** field. + +6. Give the rule a descriptive name and toggle **"Rule Status"** to **Enabled**. + +7. (Optional) Send a test webhook and click Save. + + +## 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. + + + +## 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) diff --git a/src/docs.json b/src/docs.json index 9809411d..6d596f5e 100644 --- a/src/docs.json +++ b/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", diff --git a/src/images/customer-guides/gong/add-rule.png b/src/images/customer-guides/gong/add-rule.png new file mode 100644 index 00000000..82a75bb0 Binary files /dev/null and b/src/images/customer-guides/gong/add-rule.png differ diff --git a/src/images/customer-guides/gong/admin-settings.png b/src/images/customer-guides/gong/admin-settings.png new file mode 100644 index 00000000..d29792c6 Binary files /dev/null and b/src/images/customer-guides/gong/admin-settings.png differ diff --git a/src/images/customer-guides/gong/automation-rules.png b/src/images/customer-guides/gong/automation-rules.png new file mode 100644 index 00000000..9990cbcf Binary files /dev/null and b/src/images/customer-guides/gong/automation-rules.png differ diff --git a/src/images/customer-guides/gong/filters.png b/src/images/customer-guides/gong/filters.png new file mode 100644 index 00000000..60200c28 Binary files /dev/null and b/src/images/customer-guides/gong/filters.png differ diff --git a/src/images/customer-guides/gong/processed-call.png b/src/images/customer-guides/gong/processed-call.png new file mode 100644 index 00000000..566da391 Binary files /dev/null and b/src/images/customer-guides/gong/processed-call.png differ diff --git a/src/images/customer-guides/gong/rule-status.png b/src/images/customer-guides/gong/rule-status.png new file mode 100644 index 00000000..26ae64c6 Binary files /dev/null and b/src/images/customer-guides/gong/rule-status.png differ diff --git a/src/images/customer-guides/gong/test.png b/src/images/customer-guides/gong/test.png new file mode 100644 index 00000000..538e8716 Binary files /dev/null and b/src/images/customer-guides/gong/test.png differ diff --git a/src/images/customer-guides/gong/webhook-url.png b/src/images/customer-guides/gong/webhook-url.png new file mode 100644 index 00000000..2e57b1f1 Binary files /dev/null and b/src/images/customer-guides/gong/webhook-url.png differ diff --git a/src/manifest-reference.mdx b/src/manifest-reference.mdx index 5cdbf532..0c4cffae 100644 --- 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. @@ -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/gong.mdx b/src/provider-guides/gong.mdx index 2b00b0d8..d4de4e1f 100644 --- a/src/provider-guides/gong.mdx +++ b/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 support@withampersand.com). +| 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 support@withampersand.com 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. + + **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. + ### 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. diff --git a/src/provider-guides/housecallPro.mdx b/src/provider-guides/housecallPro.mdx index b360a582..9a2f3ce8 100644 --- 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) - - In Housecall Pro’s webhook UI, this event appears as pro.created, but the - actual payload uses employee.created. - -- [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) - - Delete events for lead are not reliable due to HouseCall Pro's platform - limitations. - -- [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 index 12326a83..f281ba71 100644 --- 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 + + + 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. + + +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. diff --git a/src/subscribe-actions.mdx b/src/subscribe-actions.mdx index 9fc2acb5..73d42b08 100644 --- a/src/subscribe-actions.mdx +++ b/src/subscribe-actions.mdx @@ -6,18 +6,18 @@ With subscribe actions, you'll receive near-instant webhooks as events occur in Please note that: - - Subscribe actions are currently only supported for some providers such as Salesforce, HubSpot, Salesloft, Gmail and Zoho. Please check the [provider guides](/provider-guides/overview) to see which providers support Subscribe Actions. HubSpot requires [special set up](#special-set-up-for-hubspot) and Gmail requires [special set up](/provider-guides/google#set-up-gmail-push-notifications-for-subscribe-actions). - - They do not produce Operations or Logs that can be viewed in the Ampersand dashboard. + - Subscribe actions are supported for a subset of providers. See the [provider guides](/provider-guides/overview) to check whether your provider supports subscribe actions and whether any additional setup is required. + - Subscribe actions do not produce Operations or Logs that can be viewed in the Ampersand dashboard. - It takes 1-2 minutes, and occasionally up to 10 minutes, for the first events to arrive after the initial installation. ## Defining subscriptions -To subscribe to an object, you currently need to also have a read action specified for the object. In addition, you need to specify: +To subscribe to an object, you need to specify: - **objectName:** to indicate which object you'd like to subscribe to. This should match the name of the object in the official documentation for the SaaS API. - **destination:** the name of the [destination](/destinations) that you've defined -- **inheritFieldsAndMapping:** for now, you must always set this to `true` to inherit the mapped and unmapped fields from the Read Action. Learn more in [Fields and mapping](#fields-and-mapping). +- **inheritFieldsAndMapping:** required when using `createEvent`, `updateEvent`, `deleteEvent`, or `associationChangeEvent`. Set this to `true` so the subscribe action inherits the mapped and unmapped fields from the matching Read Action. `true` is currently the only supported value. Learn more in [Fields and mapping](#fields-and-mapping). You then need to specify the particular events you want to subscribe to. We support the following events: @@ -130,7 +130,7 @@ integrations: ### Other events -Beyond the standard events that Amperand supports, you have the ability to subscribe to any other event that that underlying platform supports. +Beyond the standard events that Ampersand supports, you have the ability to subscribe to any other event that that underlying platform supports. The event names listed in `otherEvents` must match the provider's raw event names exactly. For Salesforce this includes [events like](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/cdc_event_fields_header.htm): - `UNDELETE` @@ -139,7 +139,50 @@ For HubSpot, this includes [events like](https://developers.hubspot.com/docs/api - `{OBJECT_NAME}.restore` (e.g. `contact.restore`) - `{OBJECT_NAME}.merge` (e.g. `contact.merge`) -To listen to these other events, add `otherEvents` to your amp.yaml file: +To listen to these other events, add an `otherEvents` array to the subscribed object in your `amp.yaml`. If an object is subscribing only to `otherEvents` (no `createEvent`, `updateEvent`, or `deleteEvent`), it does not need its own matching entry in the `read` block, and `inheritFieldsAndMapping` is not required for that object. The `read` block itself must still exist on the integration. + +In the example below, the `customers` object uses create/update/delete events and therefore must have a matching read object with `inheritFieldsAndMapping: true`. The `job.appointments` object subscribes only to `otherEvents` and has no matching read entry: + +```yaml +specVersion: 1.0.0 +integrations: + - name: subscribeToHousecallPro + provider: housecallPro + read: + objects: + - objectName: customers + destination: housecallProWebhook + schedule: "*/10 * * * *" + requiredFields: + - fieldName: id + optionalFieldsAuto: all + backfill: + defaultPeriod: + days: 15 + subscribe: + objects: + - objectName: customers + destination: housecallProWebhook + inheritFieldsAndMapping: true + createEvent: + enabled: always + updateEvent: + enabled: always + watchFieldsAuto: all + deleteEvent: + enabled: always + + - objectName: job.appointments # Only otherEvents — no matching read entry needed + destination: housecallProWebhook + otherEvents: # Must match the provider's raw event names exactly + - job.appointment.scheduled + - job.appointment.rescheduled + - job.appointment.appointment_discarded + - job.appointment.appointment_pros_assigned + - job.appointment.appointment_pros_unassigned +``` + +You can also combine `otherEvents` with standard events on the same object. In this Salesforce example, the `account` object subscribes to both `createEvent` and the non-standard `UNDELETE` event. Because it uses `createEvent`, it requires a matching read entry and `inheritFieldsAndMapping: true`: ```yaml specVersion: 1.0.0 @@ -155,11 +198,13 @@ integrations: enabled: always otherEvents: - UNDELETE - read: # Read action is required + read: # Required because `account` uses createEvent objects: - objectName: account destination: accountWebhook - ... + requiredFields: + - fieldName: id + - fieldName: name ``` ### Specify backfill behavior @@ -239,114 +284,6 @@ integrations: # Omit schedule and backfill ``` -## Special set up for HubSpot - - - 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. - - -To enable HubSpot subscribe actions, you will need to: -- Define the subscribe action in your `amp.yaml` file and then deploy it, please refer to the previous section. -- Make modifications to the HubSpot app. - - -### 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, the then follow the instructions in the [HubSpot provider guide](/provider-guides/hubspot#method-1%3A-new-project-apps) 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: - ``` - 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) - ## Fields and mapping Your read action's set of fields and field mappings will apply to the subscribe action. When we deliver you the webhook, it will contain `fields` and `mappedFields` based on the fields and mapped fields from your read action. You can learn more in [Object and field mapping](/object-and-field-mapping).