Pipedrive API Documentation

The testing-readme Developer Hub

Welcome to the testing-readme developer hub. You'll find comprehensive guides and documentation to help you start working with testing-readme as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Guide for Webhooks

Last updated January 22, 2019

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.

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 > Webhooks. The max limit of webhooks is 40 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.

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,
      "type": "general",
      "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"
  }

Retry field explanation

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)

The meta block

The meta block includes the webhooks version (currently, it's version 1).

Supported event actions

  • added
  • deleted
  • merged
  • updated

Supported object types

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

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.

The only combination of event actions and object types that you can't do in Pipedrive is merge.user. You can set up the notifications for this event, but it will never send any notifications as merging users is not possible in Pipedrive.

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.

Since January 28, 2019 Pipedrive has applied a Ban System to 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.

Guide for Webhooks


Last updated January 22, 2019

Suggested Edits are limited on API Reference Pages

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