# September 8, 2026 

** September 8, 2026 Karbon API release adds batch webhook subscriptions (preview), letting you subscribe to multiple resource types under one subscription and receive events in batches. **
---

This is a **preview** — we don't expect breaking changes, but the shape may evolve based on feedback.

## Multi-Type and Batched Webhook Subscriptions

`POST /v3/WebhookSubscriptions` now supports two independent additions: subscribing to a **set** of resource types under one subscription, and receiving notifications in batches instead of one delivery per change. Each can be used on its own — we recommend combining them when subscribing to multiple types, since a multi-type subscription without batching means one delivery per change across every subscribed type.

### Subscribing to multiple types

Pass an array of `WebhookTypes` instead of `WebhookType` to create a multi-type subscription:

```http
POST /v3/WebhookSubscriptions
```

```json
{
  "TargetUrl": "https://your-app.example.com/webhooks/karbon",
  "WebhookTypes": ["Contact", "Work"]
}
```

A multi-type subscription can mix any of the selected types. Existing single-type subscriptions (`WebhookType: "Contact"`, `"Work"`, etc.) are unaffected — there's still only one multi-type subscription per API application.

Retrieve, replace, or remove a `Multi` subscription with:

```http
GET https://api.karbonhq.com/v3/WebhookSubscriptions/Multi
```

```http
PATCH https://api.karbonhq.com/v3/WebhookSubscriptions/Multi
```

```json
{
  "WebhookTypes": ["Contact", "Work", "Note"]
}
```

`PATCH` replaces the full set of subscribed types and returns a `204`. Patching a multi-type subscription that doesn't exist yet returns a `404` — create it first with a `POST` carrying `WebhookTypes`.

```http
DELETE https://api.karbonhq.com/v3/WebhookSubscriptions/Multi
```

### Batched delivery

Set `BatchSize` and `BatchMaxDelaySeconds` on create to receive notifications in batches rather than one per change — independently of whether the subscription is single-type or multi-type:

```json
{
  "TargetUrl": "https://your-app.example.com/webhooks/karbon",
  "WebhookType": "Work",
  "BatchSize": 10,
  "BatchMaxDelaySeconds": 0
}
```

With `BatchSize: 10`, Karbon accumulates up to 10 notifications and delivers them together in a single `POST`, wrapped in a batch envelope — instead of the usual single notification object — once the batch is full or the delay window elapses:

```json
{
  "BatchId": "70575b82-9a31-4576-a4e7-61e20c42189d",
  "Count": 3,
  "Events": [
    { "ResourcePermaKey": "3GBF6TnYRc7C", "ResourceType": "WorkItem", "ActionType": "Inserted", "Timestamp": "2026-09-02T03:49:42Z" },
    { "ResourcePermaKey": "tmNwbV28XGs", "ResourceType": "WorkItem", "ActionType": "Inserted", "Timestamp": "2026-09-02T03:49:42Z" },
    { "ResourcePermaKey": "tmNwbV28XGs", "ResourceType": "WorkItem", "ActionType": "Updated", "Timestamp": "2026-09-02T03:49:42Z" }
  ]
}
```

`BatchSize` is a hard cap (max `100`): once a batch reaches it, later events start a new batch rather than being appended. Omitting `BatchSize`, or setting it to `1`, keeps the existing payload format — a single notification object per `POST`.

`BatchMaxDelaySeconds` adds an additional delay on top of the existing **60-second** dispatch window before a batch is sent — `0` means no extra delay beyond that window. If your records change often and you want an additional 5 minutes before receiving a notification, you can use `"BatchMaxDelaySeconds": 300`

We recommend pairing batching with a multi-type subscription — otherwise a multi-type subscription still delivers one notification per change across every subscribed type:

```json
{
  "TargetUrl": "https://your-app.example.com/webhooks/karbon",
  "WebhookTypes": ["Contact", "Work"],
  "BatchSize": 10,
  "BatchMaxDelaySeconds": 0
}
```