Copper’s killer API feature

Copper (formerly Prosperworks) has a killer feature in their API that I just love.

Imagine if Labrador Retrievers had an API.

You wouldn’t constantly poll the poor animal to see if it wants to fetch a stick, the poor animal would go mad. What usually happens is you throw a stick when the dog nudges you with a meaningful look and a stick.

Conversely, you would feed the dog when it’s time to be fed. You wouldn’t feed it every time it nudges you with a meaningful look [1].

When APIs behave the same way, things start to look rather elegant.

You feed the API with your posts, puts, gets and deletes because you normally have something to achieve at that moment in time. But when you’re waiting for something to happen before you respond, it’s much nicer to have a more reactive way to handle things than having to poll the API to death. [2]

Copper’s API has just this separation which is fantastic. It has it’s common and garden request/response RESTful API for snooping around and POSTing things and it has a webhook infrastructure for subscribing to events.

Now this may not sound so outlandish as many platforms have a webhook feature, like SendGrid for example, but not so many of them have webhooks that can be operated via API, they are usually configured in the UI.

Returning to my Labrador, at some point you may want to stop throwing the stick every time the mad creature brings it back. You want to dial it down, take the stick away and avert your attention. Those updates aren’t useful anymore, they start to get annoying. [3]

Copper’s Webhooks are literally a subscription to a Pub/Sub topic (or whatever they have under the hood). You subscribe to something filtered or fed by the events you’re interested in and give it your endpoint.

# Extreme brevity applied below
curl --request POST \
--url 'https://api.prosperworks.com/developer_api/v1/webhooks' \
--data '{
"target": "https://your.endpoint.here",
"type": "lead",
"event": "update",
}'

Your subscription is lodged then your endpoint gets nudged with a meaningful look. When you’re done, DELETE it:

# More extreme brevity
curl --request DELETE --url \ 'https://api.prosperworks.com/developer_api/v1/webhooks/{{example_webhook_id}}'

My only gripe at this point in time is that the webhook payload only really contains the entity IDs of the records you might be interested in and not any other data or meta-data. This means you have to and GET it from the API to see if you were really interested. An overhead that I’m sure Copper will address with enough developer interest [4].

The net result is that I can programmatically subscribe and unsubscribe from the webhook as and when I feel the need to look for updates. Let’s say there’s some campaign that I want to monitor CRM activity for on a wall board or some weird behaviour in my own custom integration code that I need to monitor/debug. When I feel like it, I can take the stick away.


Webhooks are nothing new, neither are event driven systems but making them available in developer APIs is not that common and providing simple API access to control them is quite rare. Following a pub/sub paradigm of subscriptions makes things very simple, elegant and useful.


[1] unless fat labradors are your thing and you don’t really like throwing sticks

[2] consider the environment, those electrons aren’t “free”

[3] of course nobody could ever really get annoyed at a chocolate labrador called Molly

[4] meaning at least someone other than me