Ingest anything with the Webhook broker

The Webhook broker is the generic inbound connector: any HTTP client that can POST JSON — a curl one-liner, Zapier, Make, a CI job, a bespoke script — can push events into BitsWeave. Each install gets its own URL and a bearer secret; payloads land as broker messages, show up on the context graph, and can be mapped to records like any other broker's events.

Install

The contract

POST JSON to your install URL, authenticating with the secret as a bearer token:

POST /api/webhooks/<install-id>
Authorization: Bearer <secret>
Content-Type: application/json

The event type — the routing key each message is recorded under — resolves in order:

1. the X-Webhook-Event request header, else
2. an event string field on the JSON body, else
3. the literal default event.

Responses:

There is no payload schema — the broker accepts arbitrary JSON. Raw messages are retained for 7 days; the events they produce live on in the graph.

Recipe: curl

Replace the two placeholders and send:

BITSWEAVE_WEBHOOK_URL='https://bitsweave.com/api/webhooks/YOUR-INSTALL-ID'
BITSWEAVE_WEBHOOK_SECRET='YOUR-BEARER-SECRET'

curl -X POST "$BITSWEAVE_WEBHOOK_URL" \
  -H "Authorization: Bearer $BITSWEAVE_WEBHOOK_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'X-Webhook-Event: deploy.finished' \
  -d '{"service": "storefront", "version": "1.42.0", "status": "success"}'

A 200 with {"ok":true,"brokerMessageId":"…"} means the event is stored and visible under the installation's messages.

Recipe: Zapier

Use the Webhooks by Zapier action with the Custom Request event:

1. Method — POST.
2. URL — your install URL (https://bitsweave.com/api/webhooks/YOUR-INSTALL-ID).
3. Data — the JSON body, mapping in fields from earlier Zap steps, e.g. {"event": "lead.created", "email": "{{email}}", "plan": "{{plan}}"}.
4. Headers — add three rows:
   • Authorization → Bearer YOUR-BEARER-SECRET
   • Content-Type → application/json
   • X-Webhook-Event → lead.created (or rely on the event body field)

The simpler POST event works too: set Payload Type to json, put your fields under Data, and add the same Authorization and X-Webhook-Event headers.

Recipe: Make

Use the HTTP app's Make a request module:

• URL — your install URL.
• Method — POST.
• Headers — Authorization: Bearer YOUR-BEARER-SECRET and optionally X-Webhook-Event: order.updated.
• Body type — Raw; Content type — JSON (application/json).
• Request content — the JSON payload, mapping in fields from earlier modules, e.g. {"event": "order.updated", "orderId": "{{orderId}}"}.

Map events to records

Once events flow in, you can project them into custom records instead of leaving them as raw messages. With schema inference enabled, BitsWeave observes a message schema per (broker, event type) — every JSON path it has seen. A broker→record mapper wires that message schema to a record schema, one field line per sourcePath → targetFieldKey:

• In the UI, a record schema's detail page (/app/records/<schema-key>) lists its mappers; edit one at /app/records/mappers/<mapper-id> — toggle it and manage its field lines.
• Over MCP, use brokers_recordMappings_create / _update / _list (they need record:write / record:read).

Creating an enabled mapper backfills history: existing messages for that event type are projected into records without waiting for the next webhook.