Last modified: August 22, 2025
Legacy apps are still supported by HubSpot, but don’t have access to the latest app features. Learn more about the new developer platform.
Generic webhooks allow you to subscribe to events in a public app or private app to listen and react to changes to any standard CRM object (e.g., contacts, companies, etc), engagement (call, engagement, etc.), or other objects in your account.
Please note:This feature is currently in beta and is subject to change based on testing and feedback. By using this functionality, you agree to adhere to HubSpot’s Developer Terms & Developer Beta Terms. You also acknowledge the risk associated with testing an unstable API.

​
Supported object types

The following object types are currently supported when creating generic webhook subscriptions, subject to the restrictions in the alert below:
  • Appointment
  • Call
  • Cart
  • Commerce payment
  • Communication
  • Company
  • Contact
  • Course
  • Deal
  • Discount
  • Email
  • Fee
  • Feedback submission
  • Goal target
  • Invoice
  • Lead
  • Line item
  • Listing
  • Meeting event
  • Note
  • Order
  • Partner client
  • Postal mail
  • Product
  • Quote
  • Quote template
  • Service
  • Subscription
  • Task
  • Tax
  • Ticket
  • User
Please note:
  • Creating EMAIL subscriptions for the hs_email_html and hs_email_subject properties is not currently supported.
  • Creating COMMUNICATION subscriptions for the hs_communication_body property is not currently supported.
  • You can also create generic webhook subscriptions for custom objects, but only when developing a private app.
  • Generic webhook subscriptions are not currently supported for conversation.* and contact.privacyDeletion events. If you want to subscribe to these events, you should use the old format for webhooks detailed in this article.

​
Create a generic webhook in a private app

To create a generic webhook subscription in a private app:
  • In your HubSpot account, click the settings icon in the main navigation bar.
  • In the left sidebar menu, navigate to Integrations > Private Apps.
  • Click the name of your private app. If you haven’t created a private app yet, follow the instructions in this article to create one.
  • In the top right, click Edit app.
  • Click the Webhooks tab.
  • Under Target URL, enter the URL that HubSpot will make a POST request to when an event triggers.
  • Click Create subscription.
  • In the right panel, configure your subscription:
    • Click to toggle the Use expanded object support switch on.
    • Select the object types that you want to subscribe to, then select the events associated with those objects (e.g., created, merged, deleted, etc.) that will trigger HubSpot to send a request to the endpoint you configured.
    • If you select an object type that requires scopes your app hasn’t been authorized for, you’ll be prompted to add those scopes to your app.
    • If you select Property changed for the event type, you can select any of the associated object properties that you want to subscribe to changes for.
  • Click Subscribe.
create-generic-webhook-subscription-panel
  • If you don’t want your webhook subscriptions to be active immediately, or if you want to delete a subscription you mistakenly created, you can hover over the webhook and manage its status, unsubscribe to delete it, or review the subscription details. If you’ve configured multiple webhook subscriptions, you can edit their statuses in bulk by selecting the checkboxes next to each one then clicking Activate or Pause.
  • When you’re ready to save your changes, click Commit changes in the top right.
After you’ve configured your webhook subscriptions, HubSpot will begin sending POST requests to your Target URL once any of the events associated with your active subscriptions are triggered.
Please note:For each private app, HubSpot sets a concurrency limit of 10 requests when sending subscription event data. This concurrency limit is the maximum number of in-flight requests that HubSpot will attempt at a time. Each request can contain up to 100 events.

​
Create a generic webhook in a public app

To create a generic webhook subscription in your HubSpot developer account:
  • In your developer account, navigate to the Apps dashboard.
  • Click the name of an app.
  • In the left sidebar menu, navigate to Webhooks.
  • Under Target URL, enter the URL that HubSpot will make a POST request to when events trigger.
  • Click Create subscription.
  • In the right panel, configure your subscription:
    • Select the object types that you want to subscribe to, then select the events associated with those objects (e.g., created, merged, deleted) that will trigger HubSpot to send a request to the endpoint you configured.
    • If you select Property changed for the event type, you can then select any of the associated object properties that you want to subscribe to changes for.
  • Click Subscribe.
create-generic-webhook-subscription-panel
  • After you’ve created your subscription, hover over the associated object type and click View subscriptions. When you’re ready to activate the subscription, hover over the event subscription and click Activate.
activate-generic-webhook-subscription-in-public-app-settings
After you’ve configured your webhook subscriptions, HubSpot will begin sending POST requests to your Target URL once any of the events associated with your active subscriptions are triggered in an account that’s installed your app.

​
Parse generic webhook payloads

The endpoint at the target URL that you specify in your app’s webhooks settings will receive POST requests containing JSON formatted data from HubSpot. To ensure that the requests you’re getting at your webhook endpoint are actually coming from HubSpot, HubSpot populates a X-HubSpot-Signature header with a SHA-256 hash built using the client secret of your app combined with details of the request. Learn more about validating request signatures. For generic webhook payloads, the subscriptionType will follow the format of object.* (e.g., object.propertyChange instead of the previous format that was specific to each object type like contact.propertyChange). For creation, deletion, merge, restore, and property change events, the associated object type will be provided in the objectTypeId field of the payload, as defined in the table here. The tables below define the fields provided in different event payloads.

​
General

The following fields will appear in all webhook event payloads:
FieldDescription
objectIdThe ID of the object that was created, changed, or deleted. For example, for contact event changes this is the contact ID; for companies, the company ID; for deals, the deal ID; and for conversations the thread ID.
eventIdThe ID of the event that triggered this notification. This value is not guaranteed to be unique.
subscriptionIdThe ID of the subscription that triggered a notification about the event.
portalIdThe specific HubSpot account ID where the event occurred.
appIdThe ID of your public app or private app. This is used in case you have multiple applications pointing to the same webhook URL.
labelWhen this event occurred as a unix timestamp (in milliseconds).
attemptNumberStarting at 0, which number attempt this is to notify your service of this event. If your service times-out or throws an error as describe in the Retries section below, HubSpot will attempt to send the notification again.
changeSourceThe source of the change. This can be any of the change sources that appear in contact property histories.
subscriptionTypeThe webhook subscription type. This can be one of the following types: object.creation, object.deletion, object.merge, object.restore, object.propertyChange, or object.associationChange.
objectTypeIdThe type of the object that triggered the event. See the table in this article for a full reference of each objectTypeId.
sourceIdThe user or source of the triggered webhook event (e.g., a user in the HubSpot account updating a value).

​
Property change events

The following fields are specifically included in the payload of object.propertyChange events:
FieldDescription
propertyNameThe name of the object property that changed (e.g., the city property for a contact).
propertyValueThe new value of the property.

​
Merge events

The following fields are specifically included in the payload of object.merge events:
FieldDescription
primaryObjectIdThe ID of the merge winner, which is the record that remains after the merge. In the HubSpot merge UI, this is the record on the right.
mergedObjectIdsAn array of IDs that represent the records that are merged into the merge winner. In the HubSpot merge UI, this is the record on the left.
newObjectIdThe ID of the record that is created as a result of the merge. This is separate from primaryObjectId because in some cases a new record is created as a result of the merge.
numberOfPropertiesMovedAn integer representing how many properties were transferred during the merge.

​
Association events

The fields below are specifically included in the payload of object.associationChange events.
FieldDescription
fromObjectTypeIdThe ID of the object you’re associating. To find the ID values, refer to this list of object type IDs, or for contacts, companies, deals, tickets, and notes, you can use the object name (e.g., contact, company).
toObjectTypeIdThe ID of the object you’re associating the record to. To find the ID values, refer to this list of object type IDs, or for contacts, companies, deals, tickets, and notes, you can use the object name (e.g., contact, company).
associationTypeIdThe type of association you want to create. A full list of association types is provided here.
associationCategoryWhether the association type was created by HubSpot (HUBSPOT_DEFINED) or by a user (USER_DEFINED).
Association change events will trigger on both incoming and outgoing associations. This means that an object.associationChange for an objectName of contact will trigger on a DEAL_TO_CONTACT association change with toObjectTypeId: 0-1 and the corresponding associationTypeId in the payload.
Please note:
  • The associationChange event is not currently supported for custom objects.
  • Associations with user-defined labels are not currently supported with generic webhook subscriptions.