Webhooks are a powerful concept that makes integration with web applications easy. Wikipedia has a basic introduction on Webhooks. There are several advantages to using Webhooks over polling the API, such as APIs are rate limited and data needs to be synchronized to determine which data is new and which data has already been processed.
If you're looking to integrate a third party application with ClinchPad, we strongly recommend exploring webhooks. They are a clean and elegant solution that should be preferred over methods such as polling.
URL This is a URL on your server. HTTPS is not required, but it is recommended.
Handshake Key This is a an optional key that you choose as an authentication mechanism to prevent spam to your Webhook. This key will be included as a parameter when our servers call yours. If you use this key, you should compare it to your copy to validate that the submission is legit.
An HTTP POST request is sent to the specified URL with a JSON payload. Below is an example of an HTTP POST request payload when a note is added to a lead.
{
"activity":{
"_id": "52cfbf76cce8b40f0f000005",
"created_at": "2014-01-10T09:37:58Z",
"note_content": "Hello world!",
"type": "note:created",
"user": {
"_id": "52cf8c0acce8b4c375000001",
"name": "Webhook Testing",
"photo_url": "https://s3.amazonaws.com/..."
}
},
"lead":{
"_id": "52cfa124cce8b4d113000056",
"name": "Webhook T",
"stage": {
"_id": "52cf8c0bcce8b4c37500000c",
"name": "Offer"
},
"pipe": {
"_id": "52cf8c0bcce8b4c375000008",
"name": "Default"
}
},
"handshake_key": "gfhkd1asfsa"
}The handshake_key field is present only when a handshake key has been specified.
There are 33 different types of activities, listed below. Depending on the type of activities, additional fields may be present (e.g. note_content for note added activity). The full list of activities and the fields associated with them is shown in the table below.
| Activity Type | Activity Description | Fields |
|---|---|---|
| lead:created | A lead was created | |
| lead:moved | A lead was moved from one stage to another | old_stage_name, new_stage_name |
| lead:name_changed | A lead's name was changed | old_lead_name |
| lead:won | A lead was marked as won | |
| lead:lost | A lead was marked as lost | |
| lead:assigned | A lead was assigned to a user | lead_assigned_to_name |
| lead:unassigned | A lead was unassigned from a user | old_lead_assigned_to_name |
| lead:size_changed | The value of the lead was changed | lead_size, old_lead_size (if applicable) |
| lead:restored | Lead was restored from archived leads | |
| todo:created | A todo was created | todo_name, todo_type, todo_date(if applicable), todo_time (if applicable) |
| todo:name_changed | Name of a todo was changed | todo_name, old_todo_name |
| todo:type_changed | Type of a todo was changed | todo_name, todo_type, old_todo_type |
| todo:date_changed | Date of a todo was changed | todo_name, todo_date, old_todo_date (if applicable) |
| todo:time_changed | Time of a todo was changed | todo_name, todo_time, old_todo_time (if applicable) |
| todo:done_changed | Status of a todo was changed | todo_name, todo_done (true or false) |
| todo:deleted | A Todo was deleted | todo_name |
| note:created | A note was added to a lead | note_content |
| note:updated | A note was updated | note_content |
| note:deleted | A note was deleted | note_content |
| attachment:created | A file was added to a lead | attachment_filename, attachment_url |
| attachment:deleted | A file was deleted | attachment_filename |
| record:created | A field was added to a lead | record_name, record_value |
| record:updated | A field value was updated | record_name, record_value, old_record_value (if applicable) |
| record:deleted | A field was deleted | record_name, record_value |
| contact:added | A contact was added to a lead | contact_name |
| contact:removed | A contact was removed from a lead | contact_name |
| product:added | A product was added to a lead | product_name, product_quantity, product_price (if applicable) |
| product:removed | A product was removed from a lead | product_name, product_quantity |
| zone:added | A zone was added to a lead | zone_name |
| zone:removed | A zone was removed from a lead | zone_name |
| source:added | A source was added to a lead | source_name |
| source:removed | A source was removed from a lead | source_name |
| email:received | A email was added to a lead | subject |
Requestbin is a great free service for inspecting webhooks. You can create a URL there which can be used to receive requests and these requests can be inspected in a human friendly way.
If you have any problems, please send us an email to support@clinchpad.com and we will be happy to help you!