> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 5ba523fa-3f08-41ab-9078-eb785a611343
---

# Configure a webhook subscription

> Learn how to define a webhook subscription on the latest version of the developer platform.

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

```shell theme={null}
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── webhooks/
            └── webhook-hsmeta.json
```

## Webhook configuration

Below are the available configuration options for the `*-hsmeta.json` file.

```json theme={null}
{
  "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
        }
      ]
    }
  }
}
```

<p className="table-key">
  Fields marked with <span style={{ color: 'red' }}>\*</span> are required.
</p>

| Field                                                | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid`<span style={{color:"red"}}>\*</span>           | String | An internal unique identifier for the webhook component.                                                                                                                                                                                                                                                                                                                                                                                     |
| `type`<span style={{color:"red"}}>\*</span>          | String | The type of component, which should be `webhooks` in this case.                                                                                                                                                                                                                                                                                                                                                                              |
| `settings`<span style={{color:"red"}}>\*</span>      | 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`<span style={{color:"red"}}>\*</span> | Object | An object that specifies the subscription types your app will subscribe to.                                                                                                                                                                                                                                                                                                                                                                  |
| `crmObjects`                                         | Array  | <p>An array containing event subscription definitions. This is the standard array to include, and should be used for all events in the [new format](/apps/legacy-apps/public-apps/create-generic-webhook-subscriptions) (`object.*`).</p> <p>[Classic webhook subscription types](/api-reference/latest/webhooks#webhook-subscriptions) should instead be included in `legacyCrmObjects` and `hubEvents` arrays, depending on the event.</p> |
| `legacyCrmObjects`                                   | Array  | An array containing [classic subscription types](/api-reference/latest/webhooks#webhook-subscriptions), 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.                                                      |