# August 12, 2024 

** The August 12, 2024 Karbon API release includes updates to filter by Contact Type, HMAC payload signing for Webhook Subscriptions and UK specific additions to Accounting Details **
---

## Filter Organizations and Contacts by ContactType

### GET Contacts and GET Organizations
Endpoints:
* `https://api.karbonhq.com/v3/Contacts`
* `https://api.karbonhq.com/v3/Organizations`

When listing Contacts and Organizations it is now possible to filter results by Contact Type.
The filter can be specified in two ways:
* as an exact match on ContactType, e.g. `$filter=ContactType eq 'Prospect'` will match only the Contact Type `Prospect`
* as a partial match on ContactType, e.g. `$filter=contains(ContactType, 'Pro')` will match the Contact Types `Prospect` and `Service Provider`

Refer to the [Contacts API documentation](https://karbonhq.github.io/karbon-api-reference/#get-/v3/Contacts) or [Organizations API documentation](https://karbonhq.github.io/karbon-api-reference/#get-/v3/Organizations) for a full example of the response from these endpoints.

### Example use case
You want to automate the creation of check-in work items for VIP clients who have a Contact Type of `Client - VIP`.

You'll need:
* To ensure you have set up the Contact Type on your VIP clients as `Client - VIP`
* A work template for the check-in work
* An idea of when you want the work to start and be due by

Make a GET request to `https://api.karbonhq.com/v3/Organizations?$filter=ContactType eq 'Client - VIP'`. This will return a response containing a list of Organizatinons.
From here, iterate over the list, making a POST request to `https://api.karbonhq.com/v3/WorkItems` - updating the request payload to include the ClientKey of the Organization, the WorkTemplateKey of the Work Template you wish to use and any other updates to dates or assignees.

## Webhook Security enhancements

### POST WebhookSubscriptions
Endpoint: `https://api.karbonhq.com/v3/WebhookSubscriptions`

#### ⚠️ Target URLs must be secure

All newly created Webhook Subscriptions require a `TargetUrl` that the uses `https://` scheme.

**Note:** This requirement is case sensitive, i.e. URLs beginning with `HTTPS://` will not be accepted.

If the Target URL does not begin with `https://`, the following error message is returned with an HTTP `400` reponse code:

```
{
    "error": {
        "code": "4002",
        "message": "Target URL must begin with https://"
    }
}
```

#### Event timestamp in Webhook payload

A `Timestamp` property is now included in the webhook payload, denoting when the event was initially triggered. 

This is useful to:
* determine whether the message is stale and can be discarded
* avoid susceptability to replay attacks in HMAC payload signing (see below)

An example of the new Webhook payload is:

```
{
  "ResourcePermaKey": "kCsVf7svWQw",
  "ResourceType": "Contact",
  "ActionType": "Updated",
  "Timestamp": "2024-08-01T21:54:36Z"
}
```

#### HMAC Payload signing for Webhooks

It is now possible verify that Karbon was the sender of a webhook notification using a Hash-Based Message Authentication Codes (HMAC) payload signing. 
To do this, create a WebHook Subscription and include the optional property `SigningKey`.
The value assigned to `SigningKey` must be a string at least 16 characters in length, and include only alphanumeric characters `A`-`Z`, `a`-`z`, `0`-`9`, `-` and `_`.

When a webhook payload is delivered to the subscribed Target URL a `Signature` HTTP header will be included. This is a hexadecimal representation of a SHA256 hash computed using the raw webhook payload and the supplied `SigningKey` value.

**Note:** When validating the signature be sure to use the raw payload. Using a parsed or formatted version of the payload will return a different signature.

⚠️ The value assigned to `SigningKey` should be treated as a secret and not shared publically.

### Example Request
Set the `SigningKey` to `example_1234-ABCD` by making a `POST` request to `https://api.karbonhq.com/v3/WebhookSubscriptions`:
```
{
    "TargetUrl": "https://example.com/",
    "WebhookType": "Contaact",
    "SigningKey": "example_1234-ABCD"
}
```

### Example Payload Signature 

Using the `SigningKey` value `example_1234-ABCD`, the payload `{"ResourcePermaKey":"kCsVf7svWQw","ResourceType":"Contact","ActionType":"Updated","Timestamp":"2024-08-01T21:54:36Z"}` will include a `Signature` HTTP header with the value `8c42dd0e4779a2e8a56d3b8ef962238ca26f95ddc2d9abb0e76f04991a3442f3`.

**Note:** The `SigningKey` property is NOT returned in a GET request to `https://api.karbonhq.com/v3/WebhookSubscriptions`

Additional reading:
* [Hash-Based Message Authentication Codes (OKTA)](https://www.okta.com/identity-101/hmac/)
* [HMAC signature validation code examples (Github)](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries#examples)

## Additions to Accounting Details

### UK-Specific Enhancements to the Contacts API
The `/v3/Contacts` API has been updated to support additional UK-specific details within the Accounting Details section. This update affects the following endpoints:
* `GET /v3/Contacts`
* `POST /v3/Contacts`
* `PUT /v3/Contacts`

#### New Entity Types for UK Contacts
When the country is set to "UK" in Accounting Details, additional entity types are now available in the EntityType field. These include:
* Charitable Incorporated Organisation (CIO)
* Company Limited by Guarantee (CLG)
* Community Interest Company (CIC)
* Limited Liability Partnership (LLP)
* Local Authority
* Non-Departmental Public Body
* Pension Scheme
* Royal Charter
* Unincorporated Association

If the `EntityType` is set to one of the charitable entities, such as `Charitable Incorporated Organisation (CIO)`, `Company Limited by Guarantee (CLG)`, or `Royal Charter`, the API will now accept a `Charity Number` in the `RegistrationNumber` field as part of the entity’s registration details.

### Date of Signed Engagement

A new field, Date of Signed Engagement (`DateSignedEngagement`), has been added to capture the date when the engagement was officially signed. This field is relevant for both organisations and individuals.

### Example Use Case

These enhancements allow for more precise classification and compliance when managing UK-based contacts. The introduction of additional entity types ensures that all necessary legal and organisational details are recorded, particularly for charitable organisations.

### Example Request
`POST /v3/Contacts`
```
{
    "FirstName": "William",
    "LastName": "Connor",
    "EntityDescription": {
        "Text": "UK-based Community Interest Company"
    },
    "AccountingDetail": {
        "CountryCode": "UK",
        "EntityType": "Community Interest Company",
        "DateOfSignedEngagement": "2024-08-01T00:00:00Z"
    }
}
```
In this example, a new contact for a Community Interest Company (CIC) in the UK is being created, including the date of signed engagement.