What are webhooks?
Webhooks provide one way that apps can automatically send data to other apps.
What are Karbon’s webhooks?
Karbon sends webhook notices automatically for the following actions:
New or updated Contact
New or updated Organisation
New or updated Client Group
New or updated Work Item
New or updated Note
Newly created User
Newly created Invoice
Currently, only our Contact and Organisation webhooks are built into Zapier as Triggers. However, the other two options can be easily accessed through Zapier (which requires a paid plan).
What data fields trigger the webhook to be sent?
These fields cause our webhooks to be sent. However, if we see multiple updates to a record within 60 seconds, we only make one call to the end-point in the webhook subscription after updates have been stopped.
Contact
Newly created contacts as well as updates to the following fields will trigger the webhook to send:
First name
Middle name
Last name
Contact type
Email (first, top left contact card only) (first email only)
Phone number(first, top left contact card only) (first only)
Street address (first, top left contact card only) (first address)
City (first, top left contact card only) (first address)
State (first, top left contact card only) (first address)
Postcode (first, top left contact card only) (first address)
Country (first, top left contact card only) (first address)
Organisation
Newly created organisations as well as updates to the following fields will trigger the webhook to send:
Name
Contact type
Client identifier
Website (first website)
Phone number (first only)
Street address (first address)
City (first address)
State (first address)
Postcode (first address)
Country (first address)
Work Item
Newly created work as well as updates to the following fields will trigger the webhook to send:
Name
Assignee
Status
Start date
Due date
Description
Deadline Date
Note
Newly created notes as well as updates to the following fields will trigger the webhook to send:
Name
Description
Comment
User
Newly created users will trigger the webhook to send.
Invoice
New subscriptions created with the Invoice type will dispatch a notification to the subscribed URL when:
An Invoice has been sent to a client.
The status of an invoice has changed to AwaitingPayment, Paid, or Voided.
The following actions will also cause a webhook to be triggered:
Partial payments on an invoice
Moving an invoice between billing runs
Refer to the Webhook Subscriptions API documentation for a full example of the response from this endpoint.
Accessing the webhooks in Zapier
Karbon Developer Account
To utilise our API you need a developer account. Request one here.
Step 1 - Create Webhook Target URL
Create a new Zap
Choose Webhooks by Zapier as the Trigger
Event = Catch Hook
Ignore Child Key
Copy webhook URL
Step 2 - Create Webhook Subscription
Create a new Zap
Choose Schedule by Zapier as the trigger step and choose any date, this step is not needed
Choose webhooks by Zapier
Event = Custom Request
Method = POST
Data =
{
"TargetUrl": "https://hooks.zapier.com/hooks/catch/11833388/be89v1o/",
"WebhookType": "Note/WorkItem/Contact (covers ClientGroup, Contact and Organization updates)"
}Headers =
Content-Type : application/json
Authorization : This is sent to you when we register your API account. You must use the word Bearer, then a space, then the key. i.e. 'Bearer Abcefd-'
AccessKey : Paste your key found in the API app within your connected appsTest action
Your webhook has now been created.
It is possible to have multiple webhook events sent to the same URL, however you would then need to have steps to handle them differently, so it can often be easier to follow the above steps for each different webhook subscription you want to create.
Utilising the webhook data
Our webhooks only return the following data:
ResourcePermaKey: [Key]
ResourceType: [WorkItem/Note/Contact/Comment]
ActionType: [Inserted/Updated/Deleted]
Therefore to understand the underlying data a GET request needs to be sent to the relevant endpoint:
WorkItems = https://api.karbonhq.com/v3/WorkItems/[Key]
Contacts = https://api.karbonhq.com/v3/Contacts/{key}
Organization = https://api.karbonhq.com/v3/Organizations/{key}
Client Groups = https://api.karbonhq.com/v3/ClientGroups/{key}
To action this through Zapier, choose an action step Webhooks by Zapier and Event as Custom Request:
Method GET and URL as above, mapping in the Key from the Catch Webhook trigger step as follows
Add Headers
If you need support then consider our Tech Annual Service Plan.