canonical: https://jentic.com/apis/hubspot.com/hubspot-webhooks

# HubSpot Webhooks

The HubSpot Webhooks API configures the change-event subscriptions that a HubSpot app pushes to a target URL. It manages the app-level webhook settings such as target URL and throttling, and the per-event subscriptions for specific objects and event types. Subscriptions can be created, paused, batch updated, and deleted so apps stay aligned with the HubSpot data they need to react to in near real time.

## For AI agents

Manage HubSpot app webhook target URL and the change-event subscriptions that push CRM updates to that URL.

## Scope

Does not deliver outbound HTTP payloads, store webhook history, or replay missed events - use for managing HubSpot app subscription configuration only.

## Capabilities

- Read the current target URL and throttling settings for a HubSpot app's webhooks
- Update the webhook target URL and concurrency settings for an app
- Delete the app's webhook configuration to stop all delivery
- List the active event subscriptions registered on a HubSpot app
- Create a new event subscription tied to a specific object type and event
- Patch a subscription to enable, disable, or change its filter
- Batch update many subscriptions in a single call when toggling a deployment

## Use cases

### Real-time CRM sync into a data warehouse

Subscribe a HubSpot app to contact, company, and deal change events so updates land in a downstream warehouse within seconds rather than waiting for a nightly export. The throttling settings on the app webhook configuration prevent the warehouse ingestion endpoint from being overwhelmed during bulk imports.

Example prompt: Set the target with PUT /webhooks/v3/{appId}/settings, then POST /webhooks/v3/{appId}/subscriptions with eventType='contact.propertyChange' to register the subscription.

### Pause webhooks during a deployment

Disable a group of subscriptions in a single batch call before a downstream consumer is restarted, then re-enable them once the new build is healthy. The batch update endpoint avoids per-subscription round trips so the pause window is short and the risk of inconsistent state is small.

Example prompt: Call POST /webhooks/v3/{appId}/subscriptions/batch/update with {id, active:false} for the subscriptions to pause, run the deployment, then call the same endpoint with active:true.

### Decommissioning an app safely

Cleanly shut down a retired HubSpot app's event delivery by deleting its subscriptions and webhook configuration so no more events fire toward an endpoint that no longer exists. Auditing the active subscriptions first confirms what is being removed before the destructive call.

Example prompt: Call GET /webhooks/v3/{appId}/subscriptions to enumerate, DELETE each subscriptionId, then DELETE /webhooks/v3/{appId}/settings to remove the target URL configuration.

### Agent-driven webhook setup through Jentic

An AI agent handling integration onboarding searches Jentic for the HubSpot subscription create operation, loads the schema, and registers a contact-change subscription against the customer's appId. Jentic injects the developer hapikey from the vault so the agent never holds the raw credential while configuring the app.

Example prompt: Through Jentic, search 'create a HubSpot webhook subscription', load the schema for POST /webhooks/v3/{appId}/subscriptions, and execute it with eventType='contact.creation' for the customer's appId.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /webhooks/v3/{appId}/settings | Get the app's webhook configuration |
| PUT | /webhooks/v3/{appId}/settings | Update the app's webhook target URL and throttling |
| DELETE | /webhooks/v3/{appId}/settings | Remove the webhook configuration for the app |
| GET | /webhooks/v3/{appId}/subscriptions | List active subscriptions |
| POST | /webhooks/v3/{appId}/subscriptions | Create a new subscription |
| PATCH | /webhooks/v3/{appId}/subscriptions/{subscriptionId} | Update a single subscription |
| DELETE | /webhooks/v3/{appId}/subscriptions/{subscriptionId} | Delete a subscription |
| POST | /webhooks/v3/{appId}/subscriptions/batch/update | Batch update multiple subscriptions |

## Key resources

- **Settings** — Read, update, and delete the app-level webhook target URL and throttling configuration
- **Subscriptions** — Create, list, patch, batch update, and delete the per-event subscriptions on the app

## Why Jentic

- **Setup:** Wiring HubSpot Webhooks by hand means holding a developer API key, targeting api.hubapi.com, and passing it as a query parameter on every subscription call yourself. Through Jentic you install once, import HubSpot Webhooks from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API puts the app id in the URL path (/webhooks/v3/{appId}/...), so a rule can pin your agent to one app: it can read and create subscriptions for that app and nothing else. You choose the operations it may call, so deleting settings or a subscription is not included unless you add it.
- **Credential handling:** Your HubSpot developer API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a HubSpot webhook subscription', and Jentic returns the matching operation with its input schema, including the eventType and propertyName fields, so the agent calls the right endpoint without browsing the HubSpot reference docs.

## Related APIs

- **HubSpot CRM Contacts** — Contact records whose change events the webhook subscriptions deliver
- **HubSpot CRM Deals** — Deal records whose lifecycle and property change events flow through these webhooks
- **GitHub** — Webhook delivery model for source-control events rather than CRM events
- **Stripe** — Event delivery model for payment-domain events

## FAQ

### What authentication does the HubSpot Webhooks API use?

Webhook configuration calls authenticate with the HubSpot developer hapikey passed as a query parameter. Through Jentic the developer key sits in your encrypted Jentic One instance and is injected at execution time so the agent configuring webhooks never sees the raw key.

### Can I subscribe to property changes on specific HubSpot objects?

Yes. POST /webhooks/v3/{appId}/subscriptions accepts an eventType such as 'contact.propertyChange' along with a propertyName, so the subscription only fires when that specific property changes rather than on every contact update.

### What are the rate limits for the HubSpot Webhooks API?

HubSpot enforces standard public API limits - 100 requests per 10 seconds for OAuth apps and 110 per 10 seconds for developer apps. The webhook delivery itself is governed separately by the throttling settings configured on PUT /webhooks/v3/{appId}/settings.

### How do I create a webhook subscription through Jentic?

Search Jentic for 'create a HubSpot webhook subscription', load the schema for POST /webhooks/v3/{appId}/subscriptions, and execute it with the appId, eventType, and active flag. Jentic returns the new subscription record with its assigned ID.

### Can I temporarily disable a subscription without deleting it?

Yes. PATCH /webhooks/v3/{appId}/subscriptions/{subscriptionId} with active:false pauses delivery while preserving the subscription. Flip active back to true to resume without recreating the subscription.

### Does this API let me replay missed events?

No. Replay and retry behaviour is controlled by HubSpot's delivery system based on response codes from the target URL. This API only manages the subscription configuration; it does not expose a manual replay endpoint.

### Can I limit what my agent is allowed to do with the HubSpot Webhooks API?

Yes. Because you self-host Jentic One, your own rules decide which operations and credentials the agent may use, and this API puts the app id in the URL path (/webhooks/v3/{appId}/...), so a rule can pin the agent to a single app. You can allow it to read and create subscriptions for that app while withholding destructive calls, so DELETE /webhooks/v3/{appId}/settings and DELETE of a subscription are not available unless you explicitly grant them. The developer API key stays with your Jentic One instance and is injected at execution time, so the agent only ever calls the operations you approve.