Configure a webhook subscription

Webhooks enable your app to receive real-time notifications when specific events occur in a HubSpot account. Instead of repeatedly polling HubSpot’s APIs to check for changes, webhooks push event data to your application as soon as it happens. When you configure a webhook subscription, HubSpot will send a POST request to your specified endpoint whenever subscribed events occur. Your application receives the event payload, processes it, and returns a 2xx status code to acknowledge receipt.

When to use webhooks

Use webhooks when you need to:

Sync data in real-time between HubSpot and external systems (e.g., updating a contact in your database when they’re modified in HubSpot).
Trigger automated workflows based on HubSpot events (e.g., sending a Slack notification when a deal closes).
Monitor specific changes without constant API polling (e.g., tracking when contacts unsubscribe from emails).

Common use cases include CRM synchronization, notification systems, data warehousing, and integration platforms that need to stay current with HubSpot data.

Project structure

To define a set of webhook subscriptions for an app, create a webhooks directory within src/app/. Then, add a configuration file to that directory using the naming convention *-hsmeta.json.

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.

Field	Type	Description
`uid`*	String	An internal unique identifier for the webhook component.
`type`*	String	The type of component, which should be `webhooks` in this case.
`settings`*	Object	An 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`*	Object	An object that specifies the subscription types your app will subscribe to.
`crmObjects`	Array	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.
`legacyCrmObjects`	Array	An array containing classic subscription types, such as `contact.creation` and `deal.deletion`.
`hubEvents`	Array	An 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).

Field	Type	Description
`subscriptionType`	String	The type of event being subscribed to.
`objectType`	String	For subscriptions specified within the `crmObjects` array, this specifies the CRM object your app is subscribing to.
`propertyName`	String	For property change subscriptions, this specifies which property will trigger the webhook event.
`active`	Boolean	Whether webhook events will be triggered for this subscription.

​When to use webhooks

​Project structure

​Webhook configuration

When to use webhooks

Project structure

Webhook configuration