openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities Webhooks API
  version: 1.0.0
  description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.

    '
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Webhooks
  description: See <a href="https://pipedrive.readme.io/docs/guide-for-webhooks-v2?ref=api_reference" target="_blank" rel="noopener noreferrer">the guide for Webhooks</a> for more information.
paths:
  /webhooks:
    get:
      summary: Get all Webhooks
      description: Returns data about all the Webhooks of a company.
      x-token-cost: 10
      operationId: getWebhooks
      tags:
      - Webhooks
      security:
      - api_key: []
      - oauth2:
        - admin
      responses:
        '200':
          description: The list of webhooks objects from the logged in company and user
          content:
            application/json:
              schema:
                title: GetWebhooksResponse
                allOf:
                - title: BaseResponse
                  allOf:
                  - title: baseResponse
                    type: object
                    properties:
                      success:
                        type: boolean
                        description: If the response is successful or not
                  - type: object
                    properties:
                      status:
                        type: string
                        description: The status of the response
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        title: BaseWebhook
                        properties:
                          id:
                            type: integer
                            description: The ID of the Webhook
                          company_id:
                            type: integer
                            description: The ID of the company related to the Webhook
                          owner_id:
                            type: integer
                            description: The ID of the user who owns the Webhook
                          user_id:
                            type: integer
                            description: The ID of the user related to the Webhook
                          event_action:
                            type: string
                            description: The Webhook action
                          event_object:
                            type: string
                            description: The Webhook object
                          subscription_url:
                            type: string
                            description: The subscription URL of the Webhook
                          version:
                            type: string
                            description: The Webhook version
                          is_active:
                            allOf:
                            - title: numberBooleanDefault1
                              type: number
                              default: 1
                              enum:
                              - 0
                              - 1
                            description: The Webhook's status
                          add_time:
                            type: string
                            format: date-time
                            description: The date when the Webhook was added
                          remove_time:
                            type: string
                            format: date-time
                            nullable: true
                            description: The date when the Webhook was removed (if removed)
                          type:
                            type: string
                            enum:
                            - general
                            - application
                            - automation
                            description: The type of the Webhook
                          http_auth_user:
                            type: string
                            nullable: true
                            description: The username of the `subscription_url` of the Webhook
                          http_auth_password:
                            type: string
                            nullable: true
                            description: The password of the `subscription_url` of the Webhook
                          remove_reason:
                            type: string
                            nullable: true
                            description: The removal reason of the Webhook (if removed)
                          last_delivery_time:
                            type: string
                            format: date-time
                            nullable: true
                            description: The last delivery time of the Webhook
                          last_http_status:
                            type: integer
                            nullable: true
                            description: The last delivery HTTP status of the Webhook
                          admin_id:
                            type: integer
                            description: The ID of the admin of the Webhook
                          name:
                            type: string
                            description: The Webhook name
                            maxLength: 255
                      description: The array of Webhooks
              example:
                status: ok
                success: true
                data:
                - id: 1
                  company_id: 1
                  owner_id: 1
                  user_id: 1
                  event_action: added
                  event_object: activityType
                  subscription_url: http://example.org
                  version: '2.0'
                  is_active: 1
                  add_time: '2019-10-25T08:25:27.000Z'
                  remove_time: null
                  type: general
                  http_auth_user: null
                  http_auth_password: null
                  remove_reason: null
                  last_delivery_time: null
                  last_http_status: null
                  admin_id: 1
                  name: Example webhook
        '401':
          description: Unauthorized response
          content:
            application/json:
              schema:
                title: unathorizedResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  error:
                    type: string
                    description: The error message
                  errorCode:
                    type: integer
                    description: The response error code
              example:
                success: false
                error: unauthorized access
                errorCode: 401
    post:
      summary: Create a new Webhook
      description: Creates a new Webhook and returns its details. Note that specifying an event which triggers the Webhook combines 2 parameters - `event_action` and `event_object`. E.g., use `*.*` for getting notifications about all events, `create.deal` for any newly added deals, `delete.persons` for any deleted persons, etc. See <a href="https://pipedrive.readme.io/docs/guide-for-webhooks-v2?ref=api_reference" target="_blank" rel="noopener noreferrer">the guide for Webhooks</a> for more details.
      x-token-cost: 10
      operationId: addWebhook
      tags:
      - Webhooks
      security:
      - api_key: []
      - oauth2:
        - admin
      requestBody:
        content:
          application/json:
            schema:
              title: addWebhookRequest
              type: object
              required:
              - subscription_url
              - event_action
              - event_object
              - name
              properties:
                subscription_url:
                  type: string
                  description: A full, valid, publicly accessible URL which determines where to send the notifications. Please note that you cannot use Pipedrive API endpoints as the `subscription_url` and the chosen URL must not redirect to another link.
                event_action:
                  type: string
                  enum:
                  - create
                  - change
                  - delete
                  - '*'
                  description: The type of action to receive notifications about. Wildcard will match all supported actions.
                event_object:
                  type: string
                  enum:
                  - activity
                  - deal
                  - lead
                  - note
                  - organization
                  - person
                  - pipeline
                  - product
                  - stage
                  - user
                  - '*'
                  description: The type of object to receive notifications about. Wildcard will match all supported objects.
                name:
                  type: string
                  description: The webhook's name
                  maxLength: 255
                user_id:
                  type: integer
                  description: The ID of the user that this webhook will be authorized with. You have the option to use a different user's `user_id`. If it is not set, the current user's `user_id` will be used. As each webhook event is checked against a user's permissions, the webhook will only be sent if the user has access to the specified object(s). If you want to receive notifications for all events, please use a top-level admin user’s `user_id`.
                http_auth_user:
                  nullable: true
                  type: string
                  description: The HTTP basic auth username of the subscription URL endpoint (if required)
                http_auth_password:
                  nullable: true
                  type: string
                  description: The HTTP basic auth password of the subscription URL endpoint (if required)
                version:
                  type: string
                  enum:
                  - '1.0'
                  - '2.0'
                  default: '2.0'
                  description: The webhook's version. NB! Webhooks v2 is the default from March 17th, 2025. See <a href="https://developers.pipedrive.com/changelog/post/breaking-change-webhooks-v2-will-become-the-new-default-version" target="_blank" rel="noopener noreferrer">this Changelog post</a> for more details.
      responses:
        '201':
          description: The created webhook object
          content:
            application/json:
              schema:
                title: GetWebhookResponse
                allOf:
                - title: BaseResponse
                  allOf:
                  - title: baseResponse
                    type: object
                    properties:
                      success:
                        type: boolean
                        description: If the response is successful or not
                  - type: object
                    properties:
                      status:
                        type: string
                        description: The status of the response
                - type: object
                  title: GetWebhookResponseData
                  properties:
                    data:
                      type: object
                      title: BaseWebhook
                      properties:
                        id:
                          type: integer
                          description: The ID of the Webhook
                        company_id:
                          type: integer
                          description: The ID of the company related to the Webhook
                        owner_id:
                          type: integer
                          description: The ID of the user who owns the Webhook
                        user_id:
                          type: integer
                          description: The ID of the user related to the Webhook
                        event_action:
                          type: string
                          description: The Webhook action
                        event_object:
                          type: string
                          description: The Webhook object
                        subscription_url:
                          type: string
                          description: The subscription URL of the Webhook
                        version:
                          type: string
                          description: The Webhook version
                        is_active:
                          allOf:
                          - title: numberBooleanDefault1
                            type: number
                            default: 1
                            enum:
                            - 0
                            - 1
                          description: The Webhook's status
                        add_time:
                          type: string
                          format: date-time
                          description: The date when the Webhook was added
                        remove_time:
                          type: string
                          format: date-time
                          nullable: true
                          description: The date when the Webhook was removed (if removed)
                        type:
                          type: string
                          enum:
                          - general
                          - application
                          - automation
                          description: The type of the Webhook
                        http_auth_user:
                          type: string
                          nullable: true
                          description: The username of the `subscription_url` of the Webhook
                        http_auth_password:
                          type: string
                          nullable: true
                          description: The password of the `subscription_url` of the Webhook
                        remove_reason:
                          type: string
                          nullable: true
                          description: The removal reason of the Webhook (if removed)
                        last_delivery_time:
                          type: string
                          format: date-time
                          nullable: true
                          description: The last delivery time of the Webhook
                        last_http_status:
                          type: integer
                          nullable: true
                          description: The last delivery HTTP status of the Webhook
                        admin_id:
                          type: integer
                          description: The ID of the admin of the Webhook
                        name:
                          type: string
                          description: The Webhook name
                          maxLength: 255
              example:
                status: ok
                success: true
                data:
                  id: 1
                  company_id: 1
                  owner_id: 1
                  user_id: 1
                  event_action: added
                  event_object: activityType
                  subscription_url: http://example.org
                  version: '2.0'
                  is_active: 1
                  add_time: '2019-10-25T08:25:27.000Z'
                  remove_time: null
                  type: general
                  http_auth_user: null
                  http_auth_password: null
                  remove_reason: null
                  last_delivery_time: null
                  last_http_status: null
                  admin_id: 1
                  name: Example webhook
        '400':
          description: The bad response on webhook creation
          content:
            application/json:
              schema:
                title: WebhooksBadRequestResponse
                allOf:
                - title: BaseResponse
                  allOf:
                  - title: baseResponse
                    type: object
                    properties:
                      success:
                        type: boolean
                        description: If the response is successful or not
                  - type: object
                    properties:
                      status:
                        type: string
                        description: The status of the response
                - type: object
                  properties:
                    errors:
                      type: object
                      description: List of errors
              example:
                status: error
                success: false
                errors:
                  subscription_url:
                  - invalid or non-reachable URL
        '401':
          description: Unauthorized response
          content:
            application/json:
              schema:
                title: unathorizedResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  error:
                    type: string
                    description: The error message
                  errorCode:
                    type: integer
                    description: The response error code
              example:
                success: false
                error: unauthorized access
                errorCode: 401
  /webhooks/{id}:
    delete:
      summary: Delete existing Webhook
      description: Deletes the specified Webhook.
      x-token-cost: 6
      operationId: deleteWebhook
      tags:
      - Webhooks
      security:
      - api_key: []
      - oauth2:
        - admin
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: The ID of the Webhook to delete
      responses:
        '200':
          description: The webhook deletion success response
          content:
            application/json:
              schema:
                title: BaseResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    status:
                      type: string
                      description: The status of the response
              example:
                status: ok
                success: true
        '401':
          description: Unauthorized response
          content:
            application/json:
              schema:
                title: unathorizedResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  error:
                    type: string
                    description: The error message
                  errorCode:
                    type: integer
                    description: The response error code
              example:
                success: false
                error: unauthorized access
                errorCode: 401
        '403':
          description: The webhook deletion forbidden response
          content:
            application/json:
              schema:
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    message:
                      type: string
                      description: The error message
              example:
                success: false
                message: Forbidden
        '404':
          description: The webhook deletion not found response
          content:
            application/json:
              schema:
                title: WebhooksBadRequestResponse
                allOf:
                - title: BaseResponse
                  allOf:
                  - title: baseResponse
                    type: object
                    properties:
                      success:
                        type: boolean
                        description: If the response is successful or not
                  - type: object
                    properties:
                      status:
                        type: string
                        description: The status of the response
                - type: object
                  properties:
                    errors:
                      type: object
                      description: List of errors
              example:
                status: error
                success: false
                errors:
                  id:
                  - not found
components:
  securitySchemes:
    basic_authentication:
      type: http
      scheme: basic
      description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
    api_key:
      type: apiKey
      name: x-api-token
      in: header
    oauth2:
      type: oauth2
      description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.pipedrive.com/oauth/authorize
          tokenUrl: https://oauth.pipedrive.com/oauth/token
          refreshUrl: https://oauth.pipedrive.com/oauth/token
          scopes:
            base: Read settings of the authorized user and currencies in an account
            deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
            deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
            mail:read: Read mail threads and messages
            mail:full: Read, update and delete mail threads. Also grants read access to mail messages
            activities:read: Read activities, its fields and types; all files and filters
            activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types
            contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters
            contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields
            products:read: Read products, its fields, files, followers and products connected to a deal
            products:full: Create, read, update and delete products and its fields; add products to deals
            deal-fields:full: Create, read, update and delete deal fields
            product-fields:full: Create, read, update and delete product fields
            contact-fields:full: Create, read, update and delete person and organization fields
            projects:read: Read projects and its fields, tasks and project templates
            projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks
            users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers
            recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users
            search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results
            admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app
            leads:read: Read data about leads and lead labels
            leads:full: Create, read, update and delete leads and lead labels
            phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive
            goals:read: Read data on all goals
            goals:full: Create, read, update and delete goals
            video-calls: Allows application to register as a video call integration provider and create conference links
            messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses