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 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 Line Items (OpptyProductRelation) | OpptyProductRelation.*
OpptyProductRelation.Create
OpptyProductRelation.Update
OpptyProductRelation.Delete |
Register a webhook by calling this Endpoint
post
https://us-east.pipelinersales.com/api/v100/rest/spaces/<space_id>
/entities/Webhooks
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 | You can use some of the API parameters to work with webhooks
Example: You want to trigger Webhook only on Open Opportunities |
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
{
"entity": {
"Contact": {
"expand": [
"primary_account",
"primary_contact",
"task_relations.task"
],
"load-only": [
"id",
"primary_account",
"primary_contact.first_name",
"task_relations.task"
],
"filter": {
"email1": [
],
"email2": "[email protected]"
},
"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"
]
}
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/.
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.
When the Opportunity fields
Opportunity value
or closing_date
are updated on the Opportunity send notificationPOST
{{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"
}
}
}
}
}