Group Keys

What is a group key?

The group key decides which webhooks are batched together. Webbu extracts it from every incoming request, and items with the same key in the same buffer are delivered together.

It is configured on the buffer as groupKey:

{
  "groupKey": {
    "mode": "jsonpath",
    "path": "$.customerId",
    "fallbackHeader": "x-customer-id"
  }
}

Extraction rules

jsonpath mode

1. Webbu reads path from the JSON body.
2. If the value is missing or null, it reads the fallbackHeader request header (if configured).
3. If neither gives a value, the request is rejected with 400 and "error": "Could not extract group key from request". There is no default group.

path uses dot notation: $.customerId, $.data.object.customer, $.repository.full_name. Array indexes, wildcards and filters ($.items[0].id, $..id) are not supported. The value is converted to a string, so point the path at a string or number, not at an object or array.

Given this payload and "path": "$.data.object.customer":

{ "type": "invoice.paid", "data": { "object": { "customer": "cus_ABC123" } } }

the group key is cus_ABC123.

header mode

The key is read only from the fallbackHeader request header; path is ignored:

{ "groupKey": { "mode": "header", "fallbackHeader": "x-shopify-shop-domain" } }

Header names are case-insensitive.

Examples

Check that every event type you send has the field. Events without it (Stripe events without a customer, GitHub events without a repository) are rejected with 400 unless you configure a fallbackHeader that your sender always sets. To batch everything together regardless of content, send a constant header from a sender you control.

Group IDs

Webbu hashes the key, so keys of any length work:

groupHash = first 16 hex characters of sha256(groupKey)
groupId   = {bufferId}:{groupHash}:{segment}

The delivery body includes webbu.groupKey, webbu.groupHash and webbu.segment.