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