What are Webhooks?

Webhooks are a simple, efficient way of integrating with web applications. Instead of polling to see if data has been updated in OnePage, you can register a URL to which we will send POSTs containing the updated data. This has benefits for both sides.

OnePage has to respond to less API requests and you have to send less requests, reducing server load on both ends. Along with this you receive the data the moment it is available, not when you think it should be available.

Activate Webhooks in OnePageCRM

First the OnePage administrator will have to activate Webhooks on the Apps page and configure them by supplying the URL we will send hooks to and optionally add a secretkey.

The secret key will be sent with every POST, to validate that we sent the webhook and not an imposter. For added security it is advised to supply a https instead of http URL.

Configure your application

Now that we send Webhooks you can configure your server to react to the different types of data which we send. We send POSTs whose params contain the following data: a type, reason, secretkey and the data which has been updated.

Note: the data object will be empty if the object which was changed has been permanently deleted.
Element Name Type Notes
timestamp int Sent as unix time (http://en.wikipedia.org/wiki/Unix_time)
secretkey string If you provided a SecretKey it will be included here, otherwise this field is empty
data hash A data hash containing the same data as returned from a API call but as a POST parameter body.
type string What type of data was changed(Contact, Action, Deal etc..)
reason string What change triggered the Webhook(Created, Deleted, Updated etc..)

Sample Data

Note: Due to a legacy issue, the response from the contact endpoint has a slightly different format than the other endpoints. Please see the sample data.
Request Type Sample Data (json formatted)
contact
    {
      "timestamp": 1410857130,
      "secretkey": null,
      "reason": "updated",
      "type": "contact",
      "data": {
          "contact": {
              "address_list": [
                  {
                      "country_code": null,
                      "zip_code": null,
                      "state": null,
                      "city": null,
                      "address": null
                  }
              ],
              "modified_at": "2014-09-16T08:45:30Z",
              "custom_fields": [],
              "tags": [],
              "sales_closed_for": [],
              "company_id": "5417f8291da4171227000042",
              "company_name": "Cartoon Network",
              "type": "company",
              "lead_source_id": "",
              "status_id": "5417f3741da4171227000005",
              "status": "Lead",
              "emails": [
                  {
                      "value": "jb@cartoonnetwork.com",
                      "type": "work"
                  }
              ],
              "phones": [
                  {
                      "value": "+55 5555",
                      "type": "work"
                  }
              ],
              "urls": [
                  {
                      "value": "cartoonnetwork.com",
                      "type": "website"
                  }
              ],
              "background": "",
              "job_title": "Model",
              "photo_url": "",
              "last_name": "Bravo",
              "first_name": "Johnny",
              "owner_id": "5417f36d1da4171227000001",
              "id": "5417f8291da4171227000041"
          }
      }
  }
  
action
  {
    "data": {
      "id": "51c422aaceb997128700026c",
      "cid": "51a8852aceb9976888000007",
      "assignee_id": "51a88516ceb9976888000001",
      "name": "Contact Jane to confirm she has received our deal",
      "date": "26.06.2013",
      "next": false,
      "waiting": false,
      "done": false,
      "closed": "nil"
    },
    "type": "action",
    "reason": "created",
    "secretkey": "mysecretkey",
    "timestamp": "1371808446"
  }
  
deal
  {
    "data": {
      "id": "51c32a19ceb9972c1a00002d",
      "cid": "BSON::ObjectId('51a8852cceb9976888000038')",
      "name": "May deal",
      "body": "Sent him estimate today.. fingers crossed!",
      "date": "20.06.2013",
      "amount": 5130.0,
      "status": "pending",
      "closed": "nil",
      "stage": 50,
      "exp_close": "23.05.2013"
    },
    "type": "deal",
    "reason": "created",
    "secretkey": "mysecretkey",
    "timestamp": "1371744807"
  }
  
note
  {
    "data": {
      "id": "51c32989ceb9972c1a000008",
      "cid": "BSON::ObjectId('51a8852cceb9976888000038')",
      "body": "Joe just called to schedule a meeting for 03/23.",
      "date": "20.06.2013"
    },
    "type": "note",
    "reason": "created",
    "secretkey": "mysecretkey",
    "timestamp": "1371744656"
  }
Reasons
Reasons Description
Created Object has been created.
Updated Object has been updated.
Deleted The object has been deleted. If it can still be undone, then the object data will be sent along, otherwise the data object will only contain the objects id.
Undeleted Contact only: The delete action has been undone and the contact has been reactivated.
expected_close_time_updated Deal only: The expected close date for this deal has been changed.
Note: A deal can also be rescheduled in a update POST
changed_to_pending Deal only: The deal has been updated to pending, check the deal_stage param to see at what stage it is.
Note: A deal status can also be changed in an update POST
changed_to_won Deal only: The deal has been updated to won.
Note: A deal status can also be changed in an update POST
changed_to_lost Deal only: The deal has been updated to lost.
Note: A deal status can also be changed in an update POST
Completed Action only: The action has been marked as done.
Uncompleted Action only: The done action has been reopened.

Testing Webhooks

The easiest way to test the output of your webhooks is to use a service such as RequestBin or Postcatcher.in

These services will give you a URL that will collect requests made to it and let you inspect them in a human-friendly way.