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