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

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

Note

Newly created notes as well as updates to the following fields will trigger the webhook to send:

  • Name

  • Description

  • Comment

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

  1. Create a new Zap

  2. Choose Webhooks by Zapier as the Trigger

    1. Event = Catch Hook

    2. Ignore Child Key

    3. Copy webhook URL

Step 2 - Create Webhook Subscription

  1. Create a new Zap

  2. Choose Schedule by Zapier as the trigger step and choose any date, this step is not needed

  3. Choose webhooks by Zapier

    1. Event = Custom Request

    2. Method = POST

    3. URL =https://api.karbonhq.com/v3/WebhookSubscriptions

    4. Data =
      {
      "TargetUrl": "https://hooks.zapier.com/hooks/catch/11833388/be89v1o/",
      "WebhookType": "Note/WorkItem/Contact (covers ClientGroup, Contact and Organization updates)"
      }

    5. 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 apps

    6. Test action

  4. 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.

Did this answer your question?