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