Webhooks

Introduction


ClinchPad is built around the Lead entity. You can create a webhook to receive an HTTP POST event at a specified URL whenever any activity is done on a lead. To create and manage webhooks, go to Settings -> Integrations and click on Manage Interactions under the Webhooks label.

Purpose


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.

What You Need To Get Started


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.

Errors


Errors that happen show up in the Error Log and an email also sent to the creator of the webhook with details.

Format


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

Try it out


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!