With subscribe actions, you’ll receive near-instant webhooks as events occur in your customers’ SaaS applications. This enables your application to quickly react to events such as record creation, deletion, and field updates.

Subscribe actions are in beta.

  • They are currently only supported for Salesforce and HubSpot.
  • For Salesforce, an admin needs to install the integration.
  • They do not produce Operations or Logs that can be viewed in the Ampersand dashboard.

​
Salesforce subscribe actions

To subscribe to an object in Salesforce, you currently need to also have a read action specified for the object. In addition, 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 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.

You then need to specify the particular events you want to subscribe to. We support the following events:

  • createEvent: triggers when a new record is created in the SaaS application.

  • updateEvent: triggers when any existing record is modified. The watchFieldsAuto: all setting ensures that you subscribe to all field changes. Alternatively, you can list specific fields to watch in requiredWatchFields. Note: Only one of requiredWatchFields or watchFieldsAuto should be provided.

  • deleteEvent: triggers when a record is removed from the system.

If you do not already have a Salesforce integration, follow the instructions in the Salesforce provider guide to get started.

​
Specify fields to watch

You can provide fields to watch for update events and specify them in a list.

Note: Only one of requiredWatchFields or watchFieldsAuto should be provided.

Here is an example amp.yaml

specVersion: 1.0.0
integrations:
  - name: readWriteSalesforceWithInheritanceMapping
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true # for now this must be true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            requiredWatchFields:
              - phone
              - notes # this is user-defined mapped field, from read action below.
              - accountName # this is a pre-defined mapped field, from read action below.
            # watchFieldsAuto: all # alternative to `requiredWatchFields` if you wish to watch all fields
          deleteEvent:
            enabled: always
    read: # Read action is required
      objects:
        - objectName: account
          mapToName: company
          destination: accountWebhook
          requiredFields:
            - fieldName: id
            - fieldName: name
              mapToName: accountName 
            - mapToName: notes
              mapToDisplayName: Notes
              prompt: These are notes that you would like to surface in our app.
          optionalFields:
            - fieldName: annualrevenue
            - fieldName: website
        ...
    write:
      ...

For an example of a webhook message delivered according to the above amp.yaml, please see Subscribe action webhooks.

​
Specify backfill behavior

By combining subscribe actions with read actions, you can get a full picture of all the data in your customer’s SaaS instance. You can:

  • Do a full backfill when the user first installs the integration to get historic data.
  • Then, receive real-time updates about changes in their SaaS instance

Here is an example amp.yaml:

specVersion: 1.0.0
integrations: 
 - name: subscribeToSalesforce
   provider: salesforce
   subscribe:
      objects:
       - objectName: account 
         destination: myWebhook
         inheritFieldsAndMapping: true
         createEvent:
            enabled: always
         updateEvent:
            enabled: always
            watchFieldsAuto: all
         deleteEvent:
            enabled: always
   read: # Read action is required
      objects:
       - objectName: account 
         destination: myWebhook
         requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
          # Optional: read all accounts when integration is installed.
         backfill:
            defaultPeriod:
              fullHistory: true

If you do not wish to do a backfill when the integration is first installed, you can omit the backfill block in the read action definition. Because there aren’t any schedules or backfills defined, the read action won’t actually do anything but its fields and mappings will be used by the subscribe action.

specVersion: 1.0.0
integrations: 
 - name: subscribeToSalesforce
   provider: salesforce
   subscribe:
      objects:
       - objectName: account 
         destination: myWebhook
         inheritFieldsAndMapping: true
         createEvent:
            enabled: always
         updateEvent:
            enabled: always
            watchFieldsAuto: all
         deleteEvent:
            enabled: always
   read: # Read action is required
      objects:
       - objectName: account 
         destination: myWebhook
         requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
         # Omit schedule and backfill

​
HubSpot 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:

  • Have a Read Action defined for the object. You can specify backfill behavior in the Read Action, to combine backfills with subscribe actions to get a full picture of your customer’s HubSpot
  • Make modifications to the HubSpot app

If you do not yet have a HubSpot app, follow the instructions in the HubSpot provider guide to create one. Here are the steps to modify the HubSpot app to enable subscribe actions:

  1. Login to your HubSpot account.
  2. Go to the Apps section.
  3. Select your connected app.
  4. Click on Webhooks.
  5. 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.
  • Replace INTEGRATION_ID with your integration’s ID, which can be found in the Dashboard’s Home page.
  1. Click Create Subscription.
  2. Select object types, event types, and properties.
  3. Select the required checkboxes for all objects.
  4. Click Activate.

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

{
  "action": "subscribe",
  "groupName": "Demo Group",
  "groupRef": "demo-group",
  "installationId": "692428b5-22b6-417d-9478-0375949223c0",
  "installationUpdateTime": "2025-03-21T04:20:16.872886Z",
  "objectName": "account",
  "projectId": "my-project-id",
  "provider": "salesforce",
  "result": [
    {
      "fields": { // Unmapped fields from read action
        "name": "Account ABC"
      },
      "mappedFields": { // Mapped fields from read action
        "city": "San Francisco",
        "country": "USA"
      },
      "subscribeEventType": "update",
      "providerEventType": "UPDATE",
      "raw": {
        "BillingCity": "San Francisco",
        "Id": "001Pa00000W4puRIAR",
        "Name": "Account ABC",
        "attributes": {
          "type": "Account",
          "url": "/services/data/v59.0/sobjects/Account/001Pa00000W4puRIAR"
        }
      },
      "rawEvent": {
        "ChangeEventHeader": {
          "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
          "changeType": "UPDATE",
          "changedFields": [
            "Name",
            "LastModifiedDate"
          ],
          "commitNumber": 1742558812455698400,
          "commitTimestamp": 1742558812000,
          "commitUser": "005Do000000XDimIAG",
          "entityName": "Account",
          "recordId": "001Pa00000W4puRIAR",
          "sequenceNumber": 1,
          "transactionKey": "00004b85-ba97-e14f-68ca-cfa4c60f13ff"
        },
        "LastModifiedDate": "2025-03-21T12:06:52.000Z",
        "Name": "Account ABC"
      },
    }
  ],
  "resultInfo": {
    "numRecords": 1,
    "type": "inline"
  },
  "workspace": "customer-salesforce-subdomain"
}

​
Receiving data

You will receive webhook messages about events happening in your customer’s SaaS instance. These webhooks look very similar to the webhooks for read actions. See Subscribe action webhooks for more information.

With subscribe actions, you’ll receive near-instant webhooks as events occur in your customers’ SaaS applications. This enables your application to quickly react to events such as record creation, deletion, and field updates.

Subscribe actions are in beta.

  • They are currently only supported for Salesforce and HubSpot.
  • For Salesforce, an admin needs to install the integration.
  • They do not produce Operations or Logs that can be viewed in the Ampersand dashboard.

​
Salesforce subscribe actions

To subscribe to an object in Salesforce, you currently need to also have a read action specified for the object. In addition, 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 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.

You then need to specify the particular events you want to subscribe to. We support the following events:

  • createEvent: triggers when a new record is created in the SaaS application.

  • updateEvent: triggers when any existing record is modified. The watchFieldsAuto: all setting ensures that you subscribe to all field changes. Alternatively, you can list specific fields to watch in requiredWatchFields. Note: Only one of requiredWatchFields or watchFieldsAuto should be provided.

  • deleteEvent: triggers when a record is removed from the system.

If you do not already have a Salesforce integration, follow the instructions in the Salesforce provider guide to get started.

​
Specify fields to watch

You can provide fields to watch for update events and specify them in a list.

Note: Only one of requiredWatchFields or watchFieldsAuto should be provided.

Here is an example amp.yaml

specVersion: 1.0.0
integrations:
  - name: readWriteSalesforceWithInheritanceMapping
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true # for now this must be true
          createEvent:
            enabled: always
          updateEvent:
            enabled: always
            requiredWatchFields:
              - phone
              - notes # this is user-defined mapped field, from read action below.
              - accountName # this is a pre-defined mapped field, from read action below.
            # watchFieldsAuto: all # alternative to `requiredWatchFields` if you wish to watch all fields
          deleteEvent:
            enabled: always
    read: # Read action is required
      objects:
        - objectName: account
          mapToName: company
          destination: accountWebhook
          requiredFields:
            - fieldName: id
            - fieldName: name
              mapToName: accountName 
            - mapToName: notes
              mapToDisplayName: Notes
              prompt: These are notes that you would like to surface in our app.
          optionalFields:
            - fieldName: annualrevenue
            - fieldName: website
        ...
    write:
      ...

For an example of a webhook message delivered according to the above amp.yaml, please see Subscribe action webhooks.

​
Specify backfill behavior

By combining subscribe actions with read actions, you can get a full picture of all the data in your customer’s SaaS instance. You can:

  • Do a full backfill when the user first installs the integration to get historic data.
  • Then, receive real-time updates about changes in their SaaS instance

Here is an example amp.yaml:

specVersion: 1.0.0
integrations: 
 - name: subscribeToSalesforce
   provider: salesforce
   subscribe:
      objects:
       - objectName: account 
         destination: myWebhook
         inheritFieldsAndMapping: true
         createEvent:
            enabled: always
         updateEvent:
            enabled: always
            watchFieldsAuto: all
         deleteEvent:
            enabled: always
   read: # Read action is required
      objects:
       - objectName: account 
         destination: myWebhook
         requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
          # Optional: read all accounts when integration is installed.
         backfill:
            defaultPeriod:
              fullHistory: true

If you do not wish to do a backfill when the integration is first installed, you can omit the backfill block in the read action definition. Because there aren’t any schedules or backfills defined, the read action won’t actually do anything but its fields and mappings will be used by the subscribe action.

specVersion: 1.0.0
integrations: 
 - name: subscribeToSalesforce
   provider: salesforce
   subscribe:
      objects:
       - objectName: account 
         destination: myWebhook
         inheritFieldsAndMapping: true
         createEvent:
            enabled: always
         updateEvent:
            enabled: always
            watchFieldsAuto: all
         deleteEvent:
            enabled: always
   read: # Read action is required
      objects:
       - objectName: account 
         destination: myWebhook
         requiredFields:
            - fieldName: name
            - fieldName: billingcity
              mapToName: city
              mapToDisplayName: City
            - mapToName: country
              mapToDisplayName: Country
              prompt: Which field is the country for the account?
         # Omit schedule and backfill

​
HubSpot 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:

  • Have a Read Action defined for the object. You can specify backfill behavior in the Read Action, to combine backfills with subscribe actions to get a full picture of your customer’s HubSpot
  • Make modifications to the HubSpot app

If you do not yet have a HubSpot app, follow the instructions in the HubSpot provider guide to create one. Here are the steps to modify the HubSpot app to enable subscribe actions:

  1. Login to your HubSpot account.
  2. Go to the Apps section.
  3. Select your connected app.
  4. Click on Webhooks.
  5. 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.
  • Replace INTEGRATION_ID with your integration’s ID, which can be found in the Dashboard’s Home page.
  1. Click Create Subscription.
  2. Select object types, event types, and properties.
  3. Select the required checkboxes for all objects.
  4. Click Activate.

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

{
  "action": "subscribe",
  "groupName": "Demo Group",
  "groupRef": "demo-group",
  "installationId": "692428b5-22b6-417d-9478-0375949223c0",
  "installationUpdateTime": "2025-03-21T04:20:16.872886Z",
  "objectName": "account",
  "projectId": "my-project-id",
  "provider": "salesforce",
  "result": [
    {
      "fields": { // Unmapped fields from read action
        "name": "Account ABC"
      },
      "mappedFields": { // Mapped fields from read action
        "city": "San Francisco",
        "country": "USA"
      },
      "subscribeEventType": "update",
      "providerEventType": "UPDATE",
      "raw": {
        "BillingCity": "San Francisco",
        "Id": "001Pa00000W4puRIAR",
        "Name": "Account ABC",
        "attributes": {
          "type": "Account",
          "url": "/services/data/v59.0/sobjects/Account/001Pa00000W4puRIAR"
        }
      },
      "rawEvent": {
        "ChangeEventHeader": {
          "changeOrigin": "com/salesforce/api/soap/63.0;client=SfdcInternalAPI/",
          "changeType": "UPDATE",
          "changedFields": [
            "Name",
            "LastModifiedDate"
          ],
          "commitNumber": 1742558812455698400,
          "commitTimestamp": 1742558812000,
          "commitUser": "005Do000000XDimIAG",
          "entityName": "Account",
          "recordId": "001Pa00000W4puRIAR",
          "sequenceNumber": 1,
          "transactionKey": "00004b85-ba97-e14f-68ca-cfa4c60f13ff"
        },
        "LastModifiedDate": "2025-03-21T12:06:52.000Z",
        "Name": "Account ABC"
      },
    }
  ],
  "resultInfo": {
    "numRecords": 1,
    "type": "inline"
  },
  "workspace": "customer-salesforce-subdomain"
}

​
Receiving data

You will receive webhook messages about events happening in your customer’s SaaS instance. These webhooks look very similar to the webhooks for read actions. See Subscribe action webhooks for more information.