Guide for Webhooks v2 (BETA)

📘

This guide focuses on version 2 (v2) of 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.

🚧

1. Please remember that webhooks v2 is still in BETA, so it may be subject to change
2. If you need pipeline, stage or activityType events, you’ll have to use version 1 (v1) of our webhooks for now, as these events are currently unavailable for v2

About webhooks

---

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

Webhooks v2 brings added reliability and stability by reducing duplicate and missing webhook triggers and delays and giving you better debugging capabilities. In addition, you can now createlead webhooks in v2.

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.

The maximum limit of webhooks is 40 different webhooks per user.

---

How to create webhooks v2 via API

---

At the moment, you can only create webhooks v2 via API. To do this, please ensure you add the version parameter to the webhook request body.

You will be able to see the v2 webhooks you’ve created in the Pipedrive web app via Settings > Tools and apps > (Tools) > Webhooks.

POST/v1/webhooks
Creates a new Webhook and returns its details. Specifying an event that 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.

Body parameters
application/json

subscription_url (string, required)	A full, valid, publicly accessible URL which determines where to send the notifications.NB: Pipedrive API endpoints cannot be used as the subscription_url and the chosen URL must not redirect to another link.
event_action (string, required)	The type of action to receive notifications about. Wildcard will match all supported actions.Values: create, change, delete, *
event_object (string, required)	The type of object to receive notifications about. Wildcard will match all supported objects.Values: activity, deal, lead, note, organization, person, product, user, *
version (string, optional)	Webhook version. Values: 1.0, 2.0NB: Please specify 2.0 when creating webhooks v2. If the version parameter is not specified, version 1.0 will be used as default.
user_id (integer)	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’s 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 (string)	The HTTP basic auth username of the subscription URL endpoint (if required)
http_auth_password (string)	The HTTP basic auth password of the subscription URL endpoint (if required)

---

Webhook format

---

JSON

{
    "meta": {
        "action": "create",
        "entity": "deal",
        "company_id": "xxxxx",
        "correlation_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "entity_id": "xxx",
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "is_bulk_edit": false,
        "timestamp": "2023-01-01T00:00:00.000Z",
        "type": "general",
        "user_id": "xxxxx",
        "version": "2.0",
        "webhook_id": "xxx",
        "webhook_owner_id": "xxxxxx",
        "attempt": 1,
        "host": "company.pipedrive.com"
    },
    "data": ( the object data as of this update ),
    "previous": ( the previous data of the object fields that have been changed )
 }

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

---

Attempt field explanation

---

📘

For a successful delivery, we'll accept any 2XX status code.

Anything else is counted as a failure and the retry policy will commence.

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

Attempt value	Value explanation
1	Webhook delivered on the first attempt
2	Webhook delivered on the first retry
3	Webhook delivered on the second retry
4	Webhook delivered on the third retry

---

Data and previous

---

In the data block, the standard data contains only crucial information about the entity and related/connected entities if their ids are provided. You can see the payload for webhooks v2 in the migration guide here.

In the previous block, the standard data contains only the fields that have changed.

Action	Event action	Data	Previous
Deleting objects	delete	null	last state (object)
Adding new objects	create	current state (object)	null
Updating objects	change	current state (object)	previous state (object)

---

Webhook’s meta block

---

Parameter	Examples and explanations
"action"	See supported event actions
"entity"	See supported object types
"company_id"	ID of the company where the webhook was triggered in
"correlation_id"	ID of the webhook correlation
"entity_id"	ID of the object
"id"	ID of the webhook
"is_bulk_edit"	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
"timestamp"	10 character timestamp
"type"	Type of webhook Values are shown in string: general for regular webhooks application for Marketplace apps’ webhooks
"user_id"	ID of the user who triggered the webhook
"version"	Webhooks version (in this case, it's version 2.0)
"webhook_id"	ID of the webhook
"webhook_owner_id"	ID of the user who owns the webhook
"attempt"	Retry attempt number. See retry logic for more.
"host"	{COMPANYDOMAIN}.pipedrive.com

---

Supported event actions

---

• create
• change
• delete

---

Supported object types

---

• activity
• deal
• lead
• note
• organization
• person
• product
• user

📘

View list of webhooks v2 to see all available combinations of event objects and 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 a webhook for deal ownership changes, you should choose deal as the event object and change as the event action. If you pick user as the event object, the webhook will send notifications when things, such as the user’s personal data, have been changed.

You can see all possible webhooks v2 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 and 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) the ban counter will increase by one.

When the ban 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 is set back to zero.

• If a webhook is unreachable on the first try, its ban count will increase, and the standard retry logic will be applied. If the webhook is unreachable during retries, the ban counter won’t be increased.
• If a webhook is banned, the webhook’s event message is lost. No data will be saved for retries after the ban.

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