PIpipedrive
Webhooks

Create a new Webhook

Changed on

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.

post/webhooks

Request

  • Base URL
    https://api.pipedrive.com/v1
  • Auth
    • API key in header x-api-token
    • or OAuth 2
      Authorization code: https://oauth.pipedrive.com/oauth/authorize
      Token URL: https://oauth.pipedrive.com/oauth/token scopes: admin

Request body

subscription_urlstring required

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'create' | 'change' | 'delete' | '*' required

The type of action to receive notifications about. Wildcard will match all supported actions.

event_object'activity' | 'deal' | 'lead' | 'note' | 'organization' | 'person' | 'pipeline' | 'product' | 'stage' | 'user' | '*' required

The type of object to receive notifications about. Wildcard will match all supported objects.

namestring required

The webhook's name

user_idinteger

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_userstring nullable

The HTTP basic auth username of the subscription URL endpoint (if required)

http_auth_passwordstring nullable

The HTTP basic auth password of the subscription URL endpoint (if required)

version'1.0' | '2.0'

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.

Response

The created webhook object

successboolean

If the response is successful or not

statusstring

The status of the response

Changes

  • cc7952f2605bRevision changes
    • breaking

      added the new required request property

    • warning

      removed the optional property // from the response with the status

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • 5c2800de8edbRevision changes
    • info

      endpoint added