Avoid Polling With REST hooks

REST hooks are a powerful tool that enables you to trigger notifications when certain events take place in Capsule.

Why use webhooks?

When developing an integration with us, you may need to keep in sync with events that happen in Capsule. Historically this was usually done by repeatedly polling an endpoint that returns a list, sorted by some date. The main downsides to this approach are:

  • Delays - You're not hearing about events as soon as they happen, and instead have to wait until the next time your service polls to fetch new information.
  • Overhead - There will be large periods of time where no changes might happen on the account, but polling requests are sent anyway. This causes unnecessary overhead for both the client and the server.

Webhooks solve this issue by sending you the information as and when events happen. You can subscribe to certain actions in Capsule (such as a party being created, or a task being completed) and we'll let your application know when that action is triggered.

Available events

REST hooks can be set up for the following combinations of entities and operations:

  • party/{created/updated/deleted}
  • kase/{created/updated/deleted/closed/moved}
  • opportunity/{created/updated/deleted/closed/moved}
  • task/{created/updated/completed}
  • user/{created/updated/deleted}

For example, party/created, kase/deleted, user/updated. The opportunity/moved and kase/moved events will be triggered when an existing opportunity or project is moved to a different milestone or stage, respectively.

If you have a use case for any additional triggers, do send us an email and we'll consider them.

Limitations

  • Hooks must be managed by account administrators.
  • Accounts are limited to 20 subscriptions at once.
  • Only registered applications can manage subscriptions (you must be authenticated using the full OAuth flow).

Use case scenario

Assuming you wanted to have the URL https://some.url.com notified whenever a party is created:

  1. Register a client / registered application and set up your application to use the OAuth flow, authenticating as the client. You can see documentation regarding how to set up a registered application and how to authenticate here.
  2. Your application sends a POST request to Capsule to subscribe a new REST hook with the following body:
{
    "restHook": {
        "targetUrl": "https://some.url.com",
        "event": "party/created",
        "description": "An epic webhook that will change the world"
    }
}
  1. Your application then listens on the given targetUrl for incoming requests. On creating a new party in Capsule, Capsule will send a POST request to the targetUrl with the following body:
{
    "event": "party/created",
    "payload": [{
        "id": 11587,
        "type": "person",
        "about": null,
        "title": null,
        "firstName": "Scott",
        "lastName": "Spacey",
        "jobTitle": "Creative Director",
        "createdAt": "2015-09-15T10:43:23Z",
        "updatedAt": "2015-09-15T10:43:23Z",
        "organisation": null,
        "lastContactedAt": null,
        "addresses": [
            {
                "id": 12135,
                "type": null,
                "city": "Chicago",
                "country": "United States",
                "street": "847 North Rush Street",
                "state": "IL",
                "zip": "65629"
            }
        ],
        "phoneNumbers": [
            {
                "id": 12133,
                "type": null,
                "number": "773-338-7786"
            }
        ],
        "websites": [],
        "emailAddresses": [
            {
                "id": 12134,
                "type": "Work",
                "address": "scott@homestyleshop.co"
            }
        ],
        "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
    }]
}
  1. The application keeps the hook registered for as long as it is being used.
  2. Any unused hooks should be unsubscribed. When the hook is not needed anymore, the application should make a DELETE request to unsubscribe the REST hook.
  3. Alternatively, REST hooks can be deleted by making the hook's targetUrl return a 410 - Gone. A 410 returned from the target URL will cause the REST hook to be deleted from Capsule.

Retry phasing

If the payload delivery fails, we will retry delivery 5 times with the following delays: 5 seconds, 1 minute, 5 minutes, 15 minutes, 15 minutes. This is giving the target URL a total of 36 minutes and 5 seconds to respond (plus any processing time). After this, the hook will be marked as dead and unsubscribed from Capsule.