Subscribe actions

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.

Please note that:

• Subscribe actions are currently only supported for some providers such as Salesforce, HubSpot, Salesloft and Zoho. Please check the provider guides to see which providers support Subscribe Actions.
• They 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:

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

• associationChangeEvent: triggers when a record’s associations have been modified. This is only supported for HubSpot. Please see Association changes.

• otherEvents: gives you the ability that listen to any other events that are available in the provide API that Ampersand doesn’t natively support. Please see Other Events.

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: subscribeToSalesforce
    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

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

Association changes

In HubSpot, association changes do not trigger update events, you must subscribe to them specifically using associationChangeEvent. On the other hand, in Salesforce, you can subscribe to fields that refer to associations (e.g. You can subscribe to update events on the accountid field of contacts).

HubSpot example:

specVersion: 1.0.0
integrations:
  - name: hubspotAssociation
    provider: hubspot
    subscribe:
      objects:
        - objectName: contacts
          destination: contactsWebhook
          inheritFieldsAndMapping: true
          associationChangeEvent:
            enabled: always
            # Whether we should retrieve the associated record
            includeFullRecords: true
    read: # Read action is required
      objects:
        - objectName: contacts
          destination: contactsWebhook
          ...

Salesforce example:

specVersion: 1.0.0
integrations:
  - name: salesforceAssociation
    provider: salesforce
    subscribe:
      objects:
        - objectName: contact
          destination: contactWebhook
          inheritFieldsAndMapping: true
          updateEvent:
            enabled: always
            requiredWatchFields:
              - accountid
    read: # Read action is required
      objects:
        - objectName: contact
          destination: contactWebhook
          ...

Other events

Beyond the standard events that Amperand supports, you have the ability to subscribe to any other event that that underlying platform supports.

For Salesforce this includes events like:

• UNDELETE

For HubSpot, this includes events like:

• {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:

specVersion: 1.0.0
integrations:
  - name: subscribeToSalesforce
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true
          createEvent:
            enabled: always
          otherEvents:
            - UNDELETE
    read: # Read action is required
      objects:
        - objectName: account
          destination: accountWebhook
          ...

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

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 [e-mail] 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 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.
• Replace INTEGRATION_ID with your integration’s ID, which can be found in the Dashboard’s Home page.

You can also edit the file with the desired objects and events you want to subscribe to. You can refer to HubSpot documentation 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.
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.

7. Click Create Subscription.
8. Select object types, event types, and properties.
9. Select the required checkboxes for all objects.
10. 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 messages about events happening in your customer’s SaaS instance. These look very similar to the messages for read actions. See Subscribe action webhooks for more information.