Custom Integration

Overview

Webbu works with any sender that posts JSON over HTTP. This guide covers a generic setup.

Steps

1. Choose the group key

Strategy	`groupKey`	Use case
By user	`{"mode": "jsonpath", "path": "$.userId"}`	All events of a user together
By resource	`{"mode": "jsonpath", "path": "$.resourceId"}`	Events of one order, ticket, …
By type	`{"mode": "jsonpath", "path": "$.eventType"}`	Events of the same type
By tenant	`{"mode": "jsonpath", "path": "$.tenantId"}`	Per-tenant batches
By header	`{"mode": "header", "fallbackHeader": "x-tenant-id"}`	When the key is only in a header

Every request must contain the key, or it is rejected with 400. See Group Keys.

2. Create a buffer

curl -X POST https://webbu.dev/api/v1/admin/buffers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $WEBBU_API_KEY" \
  -d '{
    "bufferId": "b_custom",
    "projectId": "p_app",
    "name": "Custom webhooks",
    "groupKey": { "mode": "jsonpath", "path": "$.userId" },
    "batch": { "maxItems": 100, "maxBytes": 262144, "idleTimeoutMs": 5000, "maxWaitFromFirstMs": 30000 },
    "delivery": {
      "url": "https://your-app.example.com/webhooks/batch",
      "headers": { "Authorization": "Bearer your-destination-token" }
    }
  }'

3. Point the sender to Webbu

https://webbu.dev/api/v1/ingest/p_app/b_custom

If you control the sender, also send a stable X-Idempotency-Key (or a messageId field) per event, and consider source verification.

4. Build the batch handler

app.post('/webhooks/batch', express.json({ limit: '10mb' }), async (req, res) => {
  if (req.get('authorization') !== `Bearer ${process.env.DESTINATION_TOKEN}`) {
    return res.sendStatus(401); // 4xx is not retried
  }

  const { webbu, window, items } = req.body;
  console.log(`Received ${window.itemsCount} items for group ${webbu.groupKey}`);

  for (const item of items) {
    // skip item.messageId if already processed, then:
    await processEvent(item.payload);
  }

  res.sendStatus(200); // any 2xx within 10 seconds acknowledges the batch
});

5. Test

for i in 1 2 3; do
  curl -X POST https://webbu.dev/api/v1/ingest/p_app/b_custom \
    -H "Content-Type: application/json" \
    -d "{\"event\": \"test.$i\", \"userId\": \"user_001\"}"
done

About 5 seconds after the last request (idleTimeoutMs), your endpoint receives one batch with the three events.