openapi-directory/api/hubapi.com/webhooks.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.1","servers":[{"url":"https://api.hubapi.com"}],"info":{"description":"Provides a way for apps to subscribe to certain change events in HubSpot. Once configured, apps will receive event payloads containing details about the changes at a specified target URL. There can only be one target URL for receiving event notifications per app.","title":"Webhooks Webhooks","version":"v3","x-apisguru-categories":["customer_relation"],"x-hubspot-api-use-case":"You're building a custom integration that syncs contact data with HubSpot and you need to programmatically determine when certain fields are updated in your HubSpot account.","x-hubspot-documentation-banner":"NONE","x-hubspot-introduction":"The Webhooks API allows you to subscribe to events happening in a HubSpot account with your integration installed. Rather than making an API call when an event happens in a connected account, HubSpot can send an HTTP request to an endpoint you configure.","x-hubspot-product-tier-requirements":{"cms":"STARTER","marketing":"PROFESSIONAL","sales":"PROFESSIONAL","service":"PROFESSIONAL"},"x-hubspot-related-documentation":[{"name":"Webhooks Guide","url":"https://hubspot.dev/guides/api/webhooks"}],"x-logo":{"url":"https://developers.hubspot.com/hubfs/assets/hubspot.com/buzz/HubSpotOpenGraph.png"},"x-origin":[{"format":"openapi","url":"https://api.hubspot.com/api-catalog-public/v1/apis/webhooks/v3","version":"3.0"}],"x-providerName":"hubapi.com","x-serviceName":"webhooks"},"tags":[{"name":"Settings"},{"name":"Subscriptions"}],"paths":{"/webhooks/v3/{appId}/settings":{"delete":{"operationId":"delete-/webhooks/v3/{appId}/settings_clear","parameters":[{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"responses":{"204":{"content":{},"description":"No content"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Settings"]},"get":{"operationId":"get-/webhooks/v3/{appId}/settings_getAll","parameters":[{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Settings"]},"put":{"operationId":"put-/webhooks/v3/{appId}/settings_configure","parameters":[{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsChangeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Settings"]}},"/webhooks/v3/{appId}/subscriptions":{"get":{"operationId":"get-/webhooks/v3/{appId}/subscriptions_getAll","parameters":[{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Subscriptions"]},"post":{"operationId":"post-/webhooks/v3/{appId}/subscriptions_create","parameters":[{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCreateRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Subscriptions"]}},"/webhooks/v3/{appId}/subscriptions/batch/update":{"post":{"operationId":"post-/webhooks/v3/{appId}/subscriptions/batch/update_updateBatch","parameters":[{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchInputSubscriptionBatchUpdateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponseSubscriptionResponse"}}},"description":"successful operation"},"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponseSubscriptionResponseWithErrors"}}},"description":"multiple statuses"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Subscriptions"]}},"/webhooks/v3/{appId}/subscriptions/{subscriptionId}":{"delete":{"operationId":"delete-/webhooks/v3/{appId}/subscriptions/{subscriptionId}_archive","parameters":[{"explode":false,"in":"path","name":"subscriptionId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"},{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"responses":{"204":{"content":{},"description":"No content"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Subscriptions"]},"get":{"operationId":"get-/webhooks/v3/{appId}/subscriptions/{subscriptionId}_getById","parameters":[{"explode":false,"in":"path","name":"subscriptionId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"},{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Subscriptions"]},"patch":{"operationId":"patch-/webhooks/v3/{appId}/subscriptions/{subscriptionId}_update","parameters":[{"explode":false,"in":"path","name":"subscriptionId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"},{"explode":false,"in":"path","name":"appId","required":true,"schema":{"format":"int32","type":"integer"},"style":"simple"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionPatchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}},"description":"successful operation"},"default":{"$ref":"#/components/responses/Error"}},"security":[{"developer_hapikey":[]}],"tags":["Subscriptions"]}}},"components":{"responses":{"Error":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"An error occurred."}},"schemas":{"BatchInputSubscriptionBatchUpdateRequest":{"properties":{"inputs":{"items":{"$ref":"#/components/schemas/SubscriptionBatchUpdateRequest"},"type":"array"}},"required":["inputs"],"type":"object"},"BatchResponseSubscriptionResponse":{"properties":{"completedAt":{"format":"date-time","type":"string"},"links":{"additionalProperties":{"type":"string"},"type":"object"},"requestedAt":{"format":"date-time","type":"string"},"results":{"items":{"$ref":"#/components/schemas/SubscriptionResponse"},"type":"array"},"startedAt":{"format":"date-time","type":"string"},"status":{"enum":["PENDING","PROCESSING","CANCELED","COMPLETE"],"type":"string"}},"required":["completedAt","results","startedAt","status"],"type":"object"},"BatchResponseSubscriptionResponseWithErrors":{"properties":{"completedAt":{"format":"date-time","type":"string"},"errors":{"items":{"$ref":"#/components/schemas/StandardError"},"type":"array"},"links":{"additionalProperties":{"type":"string"},"type":"object"},"numErrors":{"format":"int32","type":"integer"},"requestedAt":{"format":"date-time","type":"string"},"results":{"items":{"$ref":"#/components/schemas/SubscriptionResponse"},"type":"array"},"startedAt":{"format":"date-time","type":"string"},"status":{"enum":["PENDING","PROCESSING","CANCELED","COMPLETE"],"type":"string"}},"required":["completedAt","results","startedAt","status"],"type":"object"},"Error":{"example":{"category":"VALIDATION_ERROR","correlationId":"aeb5f871-7f07-4993-9211-075dc63e7cbf","links":{"knowledge-base":"https://www.hubspot.com/products/service/knowledge-base"},"message":"Invalid input (details will vary based on the error)"},"properties":{"category":{"description":"The error category","example":"VALIDATION_ERROR","type":"string"},"context":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Context about the error condition","example":{"invalidPropertyName":["propertyValue"],"missingScopes":["scope1","scope2"]},"type":"object"},"correlationId":{"description":"A unique identifier for the request. Include this value with any error reports or support tickets","example":"aeb5f871-7f07-4993-9211-075dc63e7cbf","format":"uuid","type":"string"},"errors":{"description":"further information about the error","items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},"links":{"additionalProperties":{"type":"string"},"description":"A map of link names to associated URIs containing documentation about the error or recommended remediation steps","example":{"knowledge-base":"https://www.hubspot.com/products/service/knowledge-base"},"type":"object"},"message":{"description":"A human readable message describing the error along with remediation steps where appropriate","example":"Invalid input (details will vary based on the error)","type":"string"},"subCategory":{"description":"A specific category that contains more specific detail about the error","type":"string"}},"required":["category","correlationId","message"],"type":"object"},"ErrorDetail":{"properties":{"code":{"description":"The status code associated with the error detail","type":"string"},"context":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Context about the error condition","example":{"missingScopes":["scope1","scope2"]},"type":"object"},"in":{"description":"The name of the field or parameter in which the error was found.","type":"string"},"message":{"description":"A human readable message describing the error along with remediation steps where appropriate","type":"string"},"subCategory":{"description":"A specific category that contains more specific detail about the error","type":"string"}},"required":["message"],"type":"object"},"SettingsChangeRequest":{"description":"New or updated webhook settings for an app.","example":{"targetUrl":"https://www.example.com/hubspot/target","throttling":{"maxConcurrentRequests":10,"period":"SECONDLY"}},"properties":{"targetUrl":{"description":"A publicly available URL for HubSpot to call where event payloads will be delivered.","example":"https://www.example.com/hubspot/target","type":"string"},"throttling":{"$ref":"#/components/schemas/ThrottlingSettings"}},"required":["targetUrl","throttling"],"type":"object"},"SettingsResponse":{"description":"Webhook settings for an app.","example":{"createdAt":"2025-06-15T13:48:43.450Z","targetUrl":"https://www.example.com/hubspot/target","throttling":{"maxConcurrentRequests":10,"period":"SECONDLY"},"updatedAt":"2025-06-15T13:48:43.450Z"},"properties":{"createdAt":{"description":"When this subscription was created. Formatted as milliseconds from the [Unix epoch](#).","format":"date-time","type":"string"},"targetUrl":{"description":"A publicly available URL for HubSpot to call where event payloads will be delivered. See [link-so-some-doc](#) for details about the format of these event payloads.","example":"https://www.example.com/hubspot/target","type":"string"},"throttling":{"$ref":"#/components/schemas/ThrottlingSettings"},"updatedAt":{"description":"When this subscription was last updated. Formatted as milliseconds from the [Unix epoch](#).","format":"date-time","type":"string"}},"required":["createdAt","targetUrl","throttling"],"type":"object"},"StandardError":{"properties":{"category":{"type":"string"},"context":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},"errors":{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},"id":{"type":"string"},"links":{"additionalProperties":{"type":"string"},"type":"object"},"message":{"type":"string"},"status":{"type":"string"},"subCategory":{"properties":{},"type":"object"}},"required":["category","context","errors","links","message","status"],"type":"object"},"SubscriptionBatchUpdateRequest":{"properties":{"active":{"type":"boolean"},"id":{"format":"int32","type":"integer"}},"required":["active","id"],"type":"object"},"SubscriptionCreateRequest":{"description":"New webhook settings for an app.","example":{"active":true,"eventType":"contact.propertyChange","propertyName":"email"},"properties":{"active":{"description":"Determines if the subscription is active or paused. Defaults to false.","example":true,"type":"boolean"},"eventType":{"description":"Type of event to listen for. Can be one of `create`, `delete`, `deletedForPrivacy`, or `propertyChange`.","enum":["contact.propertyChange","company.propertyChange","deal.propertyChange","ticket.propertyChange","product.propertyChange","line_item.propertyChange","contact.creation","contact.deletion","contact.privacyDeletion","company.creation","company.deletion","deal.creation","deal.deletion","ticket.creation","ticket.deletion","product.creation","product.deletion","line_item.creation","line_item.deletion","conversation.creation","conversation.deletion","conversation.newMessage","conversation.privacyDeletion","conversation.propertyChange","contact.merge","company.merge","deal.merge","ticket.merge","product.merge","line_item.merge","contact.restore","company.restore","deal.restore","ticket.restore","product.restore","line_item.restore","contact.associationChange","company.associationChange","deal.associationChange","ticket.associationChange","line_item.associationChange"],"example":"contact.propertyChange","type":"string"},"propertyName":{"description":"The internal name of the property to monitor for changes. Only applies when `eventType` is `propertyChange`.","example":"email","type":"string"}},"required":["eventType"],"type":"object"},"SubscriptionListResponse":{"description":"List of event subscriptions for your app","properties":{"results":{"description":"List of event subscriptions for your app","items":{"$ref":"#/components/schemas/SubscriptionResponse"},"type":"array"}},"required":["results"],"type":"object"},"SubscriptionPatchRequest":{"description":"Updated details for the subscription.","example":{"active":true},"properties":{"active":{"description":"Determines if the subscription is active or paused.","example":true,"type":"boolean"}},"type":"object"},"SubscriptionResponse":{"description":"Complete details for an event subscription.","properties":{"active":{"description":"Determines if the subscription is active or paused.","type":"boolean"},"createdAt":{"description":"When this subscription was created. Formatted as milliseconds from the [Unix epoch](#).","format":"date-time","type":"string"},"eventType":{"description":"Type of event to listen for. Can be one of `create`, `delete`, `deletedForPrivacy`, or `propertyChange`.","enum":["contact.propertyChange","company.propertyChange","deal.propertyChange","ticket.propertyChange","product.propertyChange","line_item.propertyChange","contact.creation","contact.deletion","contact.privacyDeletion","company.creation","company.deletion","deal.creation","deal.deletion","ticket.creation","ticket.deletion","product.creation","product.deletion","line_item.creation","line_item.deletion","conversation.creation","conversation.deletion","conversation.newMessage","conversation.privacyDeletion","conversation.propertyChange","contact.merge","company.merge","deal.merge","ticket.merge","product.merge","line_item.merge","contact.restore","company.restore","deal.restore","ticket.restore","product.restore","line_item.restore","contact.associationChange","company.associationChange","deal.associationChange","ticket.associationChange","line_item.associationChange"],"type":"string"},"id":{"description":"The unique ID of the subscription.","type":"string"},"propertyName":{"description":"The internal name of the property being monitored for changes. Only applies when `eventType` is `propertyChange`.","type":"string"},"updatedAt":{"description":"When this subscription was last updated. Formatted as milliseconds from the [Unix epoch](#).","format":"date-time","type":"string"}},"required":["active","createdAt","eventType","id"],"type":"object"},"ThrottlingSettings":{"description":"Configuration details for webhook throttling.","properties":{"maxConcurrentRequests":{"description":"The maximum number of concurrent HTTP requests HubSpot will attempt to make to your app.","format":"int32","type":"integer"},"period":{"description":"Time scale for this setting. Can be either `SECONDLY` (per second) or `ROLLING_MINUTE` (per minute).","enum":["SECONDLY","ROLLING_MINUTE"],"type":"string"}},"required":["maxConcurrentRequests","period"],"type":"object"}},"securitySchemes":{"developer_hapikey":{"in":"query","name":"hapikey","type":"apiKey"}}},"x-hubspot-available-client-libraries":["PHP","Node","Ruby","Python"],"x-hubspot-documentation-banner":"NONE","x-hubspot-product-tier-requirements":{"cms":"STARTER","marketing":"PROFESSIONAL","sales":"PROFESSIONAL","service":"PROFESSIONAL"}}