Pipedrive API Documentation

Pipedrive's API Docs

Welcome to Pipedrive's Developer Documentation. Here you'll find comprehensive guides and documentation to help you start working with Pipedrive's API, as well as the Changelog to see any relevant changes regarding the public API.

Guide for Webhooks

In this article, we focus on our general webhooks.
If you want to learn about our App-Specific Webhooks, which can be created only by Marketplace apps, then you can do it here.

About webhooks

Webhooks allow you to get programmatical notifications from Pipedrive about changes to your data as they happen. If you're new to webhooks, read this guide to learn more.

Rather than requiring you to pull information via our API, webhooks will push information to your endpoint. When one of those events is triggered (for example a new deal is added), Pipedrive will send this notification as an HTTP POST request, with a JSON body, to the endpoint(s) you specify.

You can create a new webhook in the Pipedrive web app via Settings > Tools and apps > (Tools) > Webhooks. The maximum limit of webhooks is 40 different webhooks per user.

  • Regular users can create/delete webhooks but only under their own Permission level.
  • Admin users can manage webhooks for all users in their company.

The user will be disabled in the Permission level's dropdown list if one has exceeded the max limit of webhooks.

Here's what the Create new webhook form looks like for the Admin user because the Permission level drop-down menu is unavailable to Regular users:

Now let us explain the parameters for events both in and outside of Pipedrive:

Events in Pipedrive

With an event, you can filter what kind of events you want to receive (few example events below).

Parameter
Description

Event action

The action done on an event object. Use *.* for all events. Supported event actions.

Event object

The object the action is done on. Use *.* for all objects. Supported event object types.

Permission level

The permission level specifies the permissions under which the webhooks are being sent out. Webhooks about objects are not sent if the selected user does not have permitted access to them.

Events in Pipedrive are triggered both from the Pipedrive UI and from the API calls.

Endpoint outside Pipedrive

Parameter
Description

Endpoint URL

An endpoint URL is the HTTP endpoint where your preferred events are sent. We can send them only to a full, valid, publicly accessible URL.

HTTP Auth username and password (if required)

HTTP auth username and HTTP auth password are optional depending on your server setup. Webhooks service will send these Basic Authentication credentials in the header of every HTTP request. To protect your data, we strongly recommend using authenticated HTTPS requests. Note that we do not support self-signed certificates.

For testing and sandboxing purposes, you could use RequestBin, Webhook Tester or ngrok.

Webhook format

{
    "v": 1,
    "matches_filters": {
      "current": [],
      "previous": []
    },
    "meta": {
      "v": 1,
      "action": "added",
      "object": "deal",
      "id": xxx,
      "company_id": xxxxx,
      "user_id": xxxxx,
      "host": "company.pipedrive.com",
      "timestamp": 1523440213,
      "timestamp_micro": 1523440213384700,
      "permitted_user_ids": [],
      "trans_pending": false,
      "is_bulk_update": false,
      "pipedrive_service_name": false,
      "matches_filters": {
        "current": [],
        "previous": []
      },
      "webhook_id": xxx
    },
    "retry": 0,
    "current": (the object data as of this update),
    "previous": (the object data prior to this update),
    "event": "event name"
  }

See the explanations for the webhook meta block's parameters here.

Retry field explanation

For a successful delivery, we'll accept any 2XX status code.
Anything other is counted as a failure and the retry policy will commence.

You can determine the amount of delivery attempts according to the value of the retry field in the payload (see the format above). Learn about the retry logic below.

Retry value
Value explanation

0

Webhook delivered on the first attempt

1

Webhook delivered on the first retry

2

Webhook delivered on the second retry

3

Webhook delivered on the third retry

Current and previous

In the current and previous blocks, the standard data of each object is placed in a way which conforms to our API Reference with the following rules:

Action
Event name
Current
Previous

Deleting objects

deleted.[object]

null

last state (object)

Adding new objects

added.[object]

current state (object)

null

Updating objects

updated.[object]

current state (object)

previous state (object)

Merging objects

merged.[object] (about the object merged into)
deleted.[object] (about the object merged)

current state (object)

null

previous state (object)

previous state (object)

Webhook's meta block

Parameter
Examples and explanations

"v"

Webhooks version (currently, it's version 1)

"object"

"id"

ID of the object

"company_id"

ID of the company where the webhook was triggered in

"user_id"

ID of the user who triggered the webhook

"host"

company.pipedrive.com, where the company represents the company name.

"timestamp"

10 character timestamp

"timestamp_micro"

16 character timestamp

"permitted_user_ids"

IDs of users who can see or have access to the object

"trans_pending"

The parameter is used for showing the status of the database transaction's commit.

Values are shown in boolean:

  • false - transaction was completed
  • true - the completion of the transaction is pending

"is_bulk_update"

Values are shown in boolean:

  • true - trigger event originated from List view with bulk operation being used
  • false - trigger event occurred after only one object was affected and the object wasn't affected by bulk operations

"pipedrive_service_name"

If the trigger for the webhook came from Pipedrive's own service we'll return the name of the service (e.g "Import"), otherwise, we'll return false.

"matches_filters"

Contains the ID of the filter only if the event was triggered from a view with applied filter to the object. If there isn't a filter applied the object doesn't match the set filter, the parameter will be displayed as empty.

"webhook_id"

ID of the webhook

"send_activity_notifications"

Appears only when the activity object was triggered.
Values are shown in boolean:

  • false - transaction was completed
  • true- the completion of the transaction is pending

"activity_notifications_language"

Appears only when the activity object was triggered.
Displays the language, which the activity notification will be displayed in. If "send_activity_notifications": false, then "activity_notifications_language":null.

Supported event actions

  • added
  • deleted
  • merged
  • updated

Supported object types

  • activity
  • activityType
  • deal
  • note
  • organization
  • person
  • pipeline
  • product
  • stage
  • user

View list of webhooks to see all available combinations of event objects and event actions for creating webhooks.

Examples and explanations

It's possible to set up notifications for events like added.organization, *.deal, updated.*, deleted.person. When setting up notifications, note that event objects are not combinations but refer back to themselves. For example, if you want to have a webhook show when a deal changes stages, you should choose deal as the event object, not stage, and then choose update as the event action. If you pick stage as the event object, the webhook will send notifications when things, such as stage name or other settings of the stage, have been changed.

You can see all possible webhooks that can be created in Pipedrive here.

Status codes for Webhooks

You can see the status of the last attempt made by your webhook(s) in the webhook dashboard. The webhooks dashboard is available under Tools and integrations > Webhooks inside Pipedrive.

There are three status code ranges or messages that are expected:

  • A 2XX status code range shows a successful delivery of your webhook request.
  • A 500 status code indicates a server error, usually on the client-side.
  • An Error status message is shown if there is a timeout of the webhook request, the webhook is blocked, or there is an internal problem on Pipedrive’s end. If you encounter this error, you can contact our support team, who can further inquire into the logs of these requests.

For a successful delivery, we'll accept any 2XX status code. Any other code or message is counted as a failure, which means the retry logic, as well as the webhooks policy, will commence.

Retry logic

Webhooks retry policy is as follows:

  • In case the original notification sending attempt fails (due to receiving a non-2XX response code or exceeding timeout of 10 seconds), we will try 3 more times: after 3, 30 and 150 seconds. If it still fails for each of those attempts, it is counted as one non-successful delivery.
  • If there are no successful deliveries on 3 consecutive days, we will delete this specific webhook.

Outgoing webhooks are not subject to our API rate limit.

Webhooks policy

The webhooks policy is applied to both general and App-Specific webhooks.

Pipedrive has a Ban System for webhooks, which means that every time the original notification sending attempt fails on the first try (due to receiving a non-2xx response code or exceeding a timeout of 10 seconds) a ban counter will increase by one. When the counter reaches 10 on a webhook, this specific webhook will be banned for 30 minutes. When the ban time is over, the webhook is reactivated and the ban counter set back to zero.

Note that if a webhook is unreachable on the first try, its ban count will be increased and then standard retry logic will be applied, but if the webhook is unreachable during retries, the ban counter won’t be increased.

If there are no successful deliveries to a webhook on 3 consecutive days, we will delete it.

Updated about a month ago


Guide for Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.