September 8, 2026

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:

POST /v3/WebhookSubscriptions

{
  "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:

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

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

{
  "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.

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:

{
  "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:

{
  "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:

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