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
