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 supported for a subset of providers. See the provider guides 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 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: 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.

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

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

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:

specVersion: 1.0.0
integrations:
  - name: subscribeToSalesforce
    provider: salesforce
    subscribe:
      objects:
        - objectName: account
          destination: accountWebhook
          inheritFieldsAndMapping: true
          createEvent:
            enabled: always
          otherEvents:
            - UNDELETE
    read: # Required because `account` uses createEvent
      objects:
        - objectName: account
          destination: accountWebhook
          requiredFields:
            - fieldName: id
            - fieldName: name

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

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.