Skip to main content
Last modified: August 22, 2025
To define a set of webhook subscriptions for an app on the new developer platform, include a webhooks directory in the project, along with a *-hsmeta.json configuration file.

​
Directory structure

project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── webhooks/
            └── webhook-hsmeta.json

​
Webhook configuration

Below are the available configuration options for the *-hsmeta.json file. 
{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        },
        {
          "subscriptionType": "contact.deletion",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

Fields marked with * are required.

FieldTypeDescription
uid*StringAn internal unique identifier for the webhook component.
type*StringThe type of component, which should be webhooks in this case.
settings*ObjectAn object that specifies two fields: targetUrl, which is the publicly available URL for HubSpot to call where event payloads will be delivered, and maxConcurrentRequests, which is the upper threshold of HTTP requests that HubSpot will make in a given time frame.
subscriptions*ObjectAn object that specifies the subscription types your app will subscribe to.
crmObjectsArray

An array containing event subscription definitions. This is the standard array to include, and should be used for all events in the new format (object.*).

Classic webhook subscription types should instead be included in legacyCrmObjects and hubEvents arrays, depending on the event.

legacyCrmObjectsArrayAn array containing classic subscription types, such as contact.creation and deal.deletion.
hubEventsArrayAn array containing the classic subscription types contact.privacyDeletion and conversation.*
For each subscription object, the following fields can be specified, based on the subscription definition type you’re subscribed to (i.e., crmObjects, legacyCrmObjects, or hubEvents) or whether you’re subscribing to a specific property change (e.g., contact.propertyChange).
FieldTypeDescription
subscriptionTypeStringThe type of event being subscribed to.
objectTypeStringFor subscriptions specified within the crmObjects array, this specifies the CRM object your app is subscribing to.
propertyNameStringFor property change subscriptions, this specifies which property will trigger the webhook event.
activeBooleanWhether webhook events will be triggered for this subscription.