LogoLogo
HomeSupport centerAPP
  • Overview
    • Quick Start
    • About the API
    • Authentication
  • API Reference
    • REST API
    • GraphQL API
  • Core API Concepts
    • Understanding the CRM Concept
    • Fields
    • API parameters
    • Dates
    • Pagination
    • Bulk Create, Update, Delete
    • Webhooks(Real-time updates)
  • Tutorials & Articles
    • Create Account
    • Create Contact
    • Create Opportunity
    • Create Product, Product Line Item
    • Create Custom Entity Record
    • Upload Document
    • Merging Accounts/Contacts
Powered by GitBook
On this page
  1. Core API Concepts

Webhooks(Real-time updates)

Webhooks allow you to get programmatic notifications from Pipeliner about changes to your data as they happen in real-time.

Rather than quiring you to pull information via the API, webhooks will push information to your endpoint when the event happens.

Example: When the webhook is registered on Account Creation, then when the Account is created Pipeliner sends to your specified URL the JSON with the body of the newly created Account.

Registering Webhooks

Registering webhook means, that you are going to set a listener on an event if something happens. Take a look at the table below which events are supported

Entity Name
Event Name

Account

Account.*

Account.Create Account.Update Account.Delete Account.DocumentLinked Account.OwnerChanged

Contact

Contact.*

Contact.Create Contact.Update Contact.Delete Contact.DocumentLinked Contact.OwnerChanged

Opportunity

Opportunity.* Opportunity.Create Opportunity.Update Opportunity.Delete Opportunity.DocumentLinked Opportunity.OwnerChanged Opportunity.Move (when the sales step is changed) Opportunity.Lost (when the Opportunity is Archived/LOst) Opportunity.Won (when the opportunity was won) Opportunity.Qualify (when the opportunity was created from Lead - Qualified)

Lead

Lead.* Lead.Create Lead.Update Lead.Delete Lead.DocumentLinked Lead.OwnerChanged

Lead.Lost (when the lead was Archived/Lost) Lead.BackToLead (when the opportunity was reverted to Lead)

Task

Task.* Task.Create Task.Update Task.Delete Task.DocumentLinked Task.OwnerChanged Task.Comment

Email

Email.* Email.Create Email.Update Email.Delete Email.DocumentLinked

Appointment

Appointment.* Appointment.Create Appointment.Update Appointment.Delete Appointment.DocumentLinked Appointment.OwnerChanged Appointment.Comment

Product

Product.*

Product.Create

Product.Update

Product.Delete

Product Line Items (OpptyProductRelation)

OpptyProductRelation.* OpptyProductRelation.Create OpptyProductRelation.Update OpptyProductRelation.Delete

Custom Entity (Records)

CustomEntity.*

CustomEntity.Create

CustomEntity.Update

CustomEntity.Delete

CustomEntity.DocumentLinked

CustomEntity.OwnerChanged

Register the Webhook

Register a webhook by calling this Endpoint

Required Fields

Required API field Name
Description

insecure_ssl

false (Recommended) If True, remote side ssl certificate will not be validated when delivering notifications.

events

See table above to see what events you can use

url

The Server URL where the Webhook body should be sent

options

Options are described below

Webhook options

Option Name
REST API format
Description

On Field change

on-field-change

Use when you want to trigger a webhook only on specific fields changes (eg. Opportunity value was changed)

Skipping webhooks

skip_keys

You can specify list of strings under "skip_keys" key in options. Whenever you make an API request with header "Webhook-Skip-Key" equal to any of the specified skip keys, the Webhook will not be triggered. This can prevent a Webhook loop. Example: Insert into every header of your Post Request the information "my integration", so Pipeliner is not sending the webhooks back whenever the record is created/updated and the record was created by request with header "my integration"

Expanding data of Linked entities

related_entity

When you want to get data about related Entity. Example: You have webhook on Opportunity. When you receive data on the Opportunity, you would like to know information about all Product Line items on the Opportunity

Api paremeters

expand, load_only, filter, filter-op

Webhook for Custom entity

custom_entity_api_name

Use when you want to trigger Webhook on Custom entities. You have to add API names of required custom entities.

Webhook throttling

chunk_size

Default:100

Defines how much data should come in one request

Webhook throttling delay

chunk_delay

Default:0

each chunk will be delayed by N * chunk_delay seconds, where N is index of chunk

Example of Option parameters

{
    "custom_entity_api_name": [ "CE_Bid", "CE_Campaign" ],	
    "entity": {
        "Contact": {
            "expand": [
                "primary_account",
                "primary_contact",
                "task_relations.task"
            ],
            "load-only": [
                "id",
                "primary_account",
                "primary_contact.first_name",
                "task_relations.task"
            ],
            "filter": {
                "email1": [
                    "test@example.com",
                    "test@example.net"
                ],
                "email2": "test@example.com"
            },
            "filter-op": {
                "email1": "eq"
            }, 
            "on-field-change": [
                "email1"
            ]
        },
        "Account": {
            "filter": {
                "owner_id": [
                    "9900cce6-bcd6-412a-bcd1-1904556c949a"
                ]
            }
        }
    },
    "related_entity": {
        "expand": [
            "contact"
        ],
        "load-only": [
            "id",
            "contact"
        ]
    },
    "skip_keys": [
        "gmail_sync",
        "custom_integration"
    ]
}

Webhooks examples

Trigger webhook when Account is created

POST 
{{baseUrl}}/entities/Webhooks
{
    "insecure_ssl": false,
    "url": "https://enrdznpu5i7jp.x.pipedream.net",
    "events": [
        "Account.Create"
    ],
    "options": {}
}

Once the webhook was registered go to the Application and create a new account. Then check the body of created Account in requestbin application.

Trigger webhook on field change

When the Opportunity fields Opportunity value or closing_date are updated on the Opportunity send notification

POST 
{{baseUrl}}/entities/Webhooks
{
    "insecure_ssl": false,
    "url": "https://enrdznpu5i7jp.x.pipedream.net",
    "events": [
        "Opportunity.Update"
    ],
    "options": {
        "entity": {
            "Opportunity": {
                "on-field-change": ["closing_date", "value"]
            }
        }
    }
}

Trigger webhook on filtered data

Listen to notifications only when the Opportunity is Opened (not won or lost). When attribute filter-op is not defined Pipeliner automatically uses "eq" value to filter the results

{
    "insecure_ssl": false,
    "url": "https://enrdznpu5i7jp.x.pipedream.net",
    "events": [
        "Opportunity.Update"
    ],
    "options": {
        "entity": {
            "Opportunity": {
                "filter":{
                    "status": "Open"
                }
            }
        }
    }
}

Webhooks for Custom Entity records

To use webhooks for custom entity, the attribute custom_entity_api_name should contain API names of required custom entities.

{
    "insecure_ssl": false,
    "url": "https://enrdznpu5i7jp.x.pipedream.net",
    "events": [
        "CustomEntity.Create", 
	"CustomEntity.Update"
    ],
    "options": {
        "custom_entity_api_name": [ "CE_Bid", "CE_Campaign" ],
        "entity": {
            "CE_Bid": {
		"filter": {
		    "name": "important"
		},
		"filter-op": {
		    "name": "contains"
		}
	    }
        }
    }
}
PreviousBulk Create, Update, DeleteNextCreate Account

Last updated 1 year ago

You can use some of the to work with webhooks Example: You want to trigger Webhook only on Open Opportunities

For testing our examples we are going to create a request bin when we will sent our webhooks. We are going to use this service .

https://requestbin.com/
API parameters
  • Registering Webhooks
  • Register the Webhook
  • POST/entities/Webhooks
  • Webhooks examples
post

Creates new webhook

Query parameters
validation-levelinteger · int32Optional

Specify validation level of webhook on create. Use them as bit mask: 0 - validate each field on entity, 2 - validate only changed fields, 4 - validate only system fields, 8 - allows to override readonly fields, 16 - allows to set entity on deleted relationship.

Body
modifiedstring · date-timeRead-onlyOptional

Last modification time.

Example: 2019-01-01T00:00:00
createdstring · date-timeRead-onlyOptional

Creation time.

Example: 2019-01-01T00:00:00
insecure_sslbooleanRequired

If True, remote side ssl certificate will not be validated when delivering notifications.

Example: false
optionsobjectOptional

Params in REST API format (snake case), to modify the content of the WebHook. You can set "entity" options of the main entity on which the event occurs. E.g. Account for events like Account.Create, Account.Update, Account.Delete. For events with a secondary related entity you can also options under key "related_entity". E.g. for Account.LinkedDocument event, the "expand" option of CloudObject(Document) can be set under "related_entity" key. Filter follows REST API conventions: http://pipeliner-api-doc.s3-website-eu-west-1.amazonaws.com/latest/rest/space/index.html In addition, to REST params, you can conditionally trigger webhook only when specified fields will change. You can use "on-field-change" param and provide a list of api names on which this change will listen.

Suppressing Webhooks You can specify list of strings under "skip_keys" key in options. Whenever you make an API request with header "Webhook-Skip-Key" equal to any of the specified skip keys, the Webhook will not be triggered. This can prevent a Webhook loop.

Example: { "entity": { "Contact": { "expand": [ "primary_account", "primary_contact", "task_relations.task" ], "load-only": [ "id", "primary_account", "primary_contact.first_name", "task_relations.task" ], "filter": { "email1": ["test@example.com", "test@example.net"], "email2": "test@example.com" }, "filter-op": {"email1": "eq"}, # optional, default operator is eq "on-field-change": ["email1"] }, "Account": { "filter": { "owner_id": ["9900cce6-bcd6-412a-bcd1-1904556c949a"] } } }, "related_entity": {"expand": ["contact"], "load-only": ["id", "contact"]}, "skip_keys": ["gmail_sync", "custom_integration"], "chunk_size": 100, // defines the size of the chunk, default is 100, max is 100. "chunk_delay": 300 // each chunk will be delayed by N * chunk_delay seconds, where N is index of chunk, default is 0. }

signaturestring · uuidOptional

Signature to verify webhook (has to be UUID). When signature is set, then all webhook requests will be signed using HMAC-SHA256. This signature will be used as key and request body as message. Signature will be located in "WebHook-Signature" header.

Example: 01234567-abcd-dcba-ffff-000000000000
urlstringRequired

Webhook URL.

Example: string
Responses
201
Creation confirmation. Returns created webhook
application/json
500
unexpected error
application / json
post
POST /api/v100/rest/spaces/<space_id>/entities/Webhooks HTTP/1.1
Host: us-east.pipelinersales.com
Content-Type: application / json
Accept: */*
Content-Length: 116

{
  "insecure_ssl": false,
  "options": {},
  "signature": "01234567-abcd-dcba-ffff-000000000000",
  "url": "string",
  "events": [
    "*"
  ]
}
{
  "success": true,
  "data": {
    "is_delete_protected": false,
    "id": "01234567-abcd-dcba-ffff-000000000000",
    "is_deleted": false,
    "modified": "2019-01-01T00:00:00",
    "created": "2019-01-01T00:00:00",
    "application": "https://example.com",
    "client": "https://example.com",
    "application_id": "01234567-abcd-dcba-ffff-000000000000",
    "client_id": "01234567-abcd-dcba-ffff-000000000000",
    "insecure_ssl": false,
    "options": {},
    "signature": "01234567-abcd-dcba-ffff-000000000000",
    "url": "string",
    "events": [
      "*"
    ]
  }
}