Webhooks API
Provides a way for apps to subscribe to certain change events in HubSpot
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"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 API",
"version": "v3",
"x-apisguru-categories": [
"customer_relation"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/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": [
{
"description": "Operations to manage app-level webhook settings.",
"name": "Settings"
},
{
"description": "Operations to manage event subscriptions.",
"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",
"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",
"type": "object"
},
"message": {
"description": "A human readable message describing the error along with remediation steps where appropriate",
"example": "An error occurred",
"type": "string"
},
"subCategory": {
"description": "A specific category that contains more specific detail about the error",
"type": "string"
}
},
"required": [
"category",
"correlationId",
"message"
],
"type": "object"
},
"ErrorCategory": {
"properties": {
"httpStatus": {
"enum": [
"CONTINUE",
"SWITCHING_PROTOCOLS",
"PROCESSING",
"OK",
"CREATED",
"ACCEPTED",
"NON_AUTHORITATIVE_INFORMATION",
"NO_CONTENT",
"RESET_CONTENT",
"PARTIAL_CONTENT",
"MULTI_STATUS",
"ALREADY_REPORTED",
"IM_USED",
"MULTIPLE_CHOICES",
"MOVED_PERMANENTLY",
"FOUND",
"SEE_OTHER",
"NOT_MODIFIED",
"USE_PROXY",
"TEMPORARY_REDIRECT",
"PERMANENT_REDIRECT",
"BAD_REQUEST",
"UNAUTHORIZED",
"PAYMENT_REQUIRED",
"FORBIDDEN",
"NOT_FOUND",
"METHOD_NOT_ALLOWED",
"NOT_ACCEPTABLE",
"PROXY_AUTHENTICATION_REQUIRED",
"REQUEST_TIMEOUT",
"CONFLICT",
"GONE",
"LENGTH_REQUIRED",
"PRECONDITION_FAILED",
"REQUEST_ENTITY_TOO_LARGE",
"REQUEST_URI_TOO_LONG",
"UNSUPPORTED_MEDIA_TYPE",
"REQUESTED_RANGE_NOT_SATISFIABLE",
"EXPECTATION_FAILED",
"IM_A_TEAPOT",
"MISDIRECTED_REQUEST",
"UNPROCESSABLE_ENTITY",
"LOCKED",
"FAILED_DEPENDENCY",
"UPGRADE_REQUIRED",
"PRECONDITION_REQUIRED",
"TOO_MANY_REQUESTS",
"REQUEST_HEADERS_FIELDS_TOO_LARGE",
"INTERNAL_STALE_SERVICE_DISCOVERY",
"UNAVAILABLE_FOR_LEGAL_REASONS",
"MIGRATION_IN_PROGRESS",
"INTERNAL_SERVER_ERROR",
"NOT_IMPLEMENTED",
"BAD_GATEWAY",
"SERVICE_UNAVAILABLE",
"GATEWAY_TIMEOUT",
"HTTP_VERSION_NOT_SUPPORTED",
"VARIANT_ALSO_NEGOTIATES",
"INSUFFICIENT_STORAGE",
"LOOP_DETECTED",
"NOT_EXTENDED",
"NETWORK_AUTHENTICATION_REQUIRED"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"httpStatus",
"name"
],
"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. See [link-so-some-doc](#) for details about the format of these event payloads.",
"type": "string"
},
"throttling": {
"$ref": "#/components/schemas/ThrottlingSettings"
}
},
"required": [
"targetUrl",
"throttling"
],
"type": "object"
},
"SettingsResponse": {
"description": "Webhook settings for an app.",
"example": {
"createdAt": "2020-01-24T16:27:59Z",
"targetUrl": "https://www.example.com/hubspot/target",
"throttling": {
"maxConcurrentRequests": 10,
"period": "SECONDLY"
},
"updatedAt": "2020-01-24T16:32:43Z"
},
"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.",
"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": {
"$ref": "#/components/schemas/ErrorCategory"
},
"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.",
"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"
],
"type": "string"
},
"propertyName": {
"description": "The internal name of the property to monitor for changes. Only applies when `eventType` is `propertyChange`.",
"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.",
"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"
],
"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 HTTP requests HubSpot will attempt to make to your app in a given time frame determined by `period`.",
"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",
"Python",
"Ruby"
]
}