Destinations: governed egress
A destination is a place Bucker sends data to: an HTTPS endpoint that receives the events and logs a filter selects, cut to the fields you name, scrubbed, and signed. It is the one door through which telemetry leaves on purpose, so it is governed like the most sensitive configuration there is: proposed by a person or an agent, approved by a person, inert until a second approval turns it on, and unable to send more than a person approved without a person's own act.
Everything on this page is opt-in and inert by default. A deployment with no destination configured sends nothing, opens no connection and stores no row.
What a destination is
| Part | What it holds |
|---|---|
| Kind | http_webhook or object_store. snowflake and bigquery are reserved and refused, naming WH-09. Two more kinds exist only as the umbrella rows below. |
| Host | An entry on your organization's egress allow-list (egressHostId). A person adds hosts; a destination can only name one that is already there, and never Bucker's own ingest or API host (the loop guard). |
| Credential | A connection (connectionId) a person binds. A destination that signs with a secret cannot go live without one. |
| Filter | A closed predicate (key, op, value, ANDed) over what is sent. No filter selects nothing. |
| Field allow-list | The only fields that leave. A field not named is never sent. |
| Tier | agent (the default, the strictest scrub) or stored. |
| Pace | A batches-a-minute limit and an optional request path under the host. |
| State | draft, enabled, paused, disabled. The delivery ledger also keeps its own pause. |
A destination never carries a URL or a secret in anything an agent can write. The schemas have no field for one.
What leaves, in order
The order is the security property, and the preview shows exactly this function's output:
- Suppressed subjects are dropped (the subject is read from the whole row, so a field that is never sent can still decide a row is not).
- Your rules for the destination run (the pipeline rules,
transformations_*). A rule whose expression cannot be evaluated holds the batch and pauses the destination; it never sends unfiltered. - The cut: only the allow-listed paths survive. It comes after the rules, because a
setor rename rule can introduce a field, and a field nobody allow-listed must not leave. - The scrub at the destination's tier, with your organization's own scrub rules.
- The signature: Standard Webhooks (
webhook-id,webhook-timestamp,webhook-signature) over exactly the bytes sent. The id is derived from the batch, so a retry is the same message to the receiver.
Delivery runs through the delivery ledger: every batch has a row, a state, attempts and a
receipt; a receiver's Retry-After is honoured; a failing hour pauses the destination and tells the
owners; a dead batch holds the position until a person replays it. Rows are sent in one-minute
windows, oldest first, starting from the moment the destination was enabled (it does not backfill
history).
Setting one up
- Preview.
POST .../destinations/preview, ordestinations_listwithinclude: [preview]and acandidate. It returns the exact payload for recent matching events at the proposed tier (no network call, by construction), the 7-day matching volume and bytes a day, the fields with the personal-data categories each may carry, the egress diff (host, fields and tier before and after), the lineage dependents (not_availableuntil the lineage package lands), and a digest good for 10 to 15 minutes. The digest is bound to your organization, the name and the resulting cut, and carries the measured volume, so the figure an approver reads is the one that was shown. - Propose.
POST .../destinationsor thedestination_proposetool, with that digest. The act ispipeline.destination.create, which always asks. The destination is filled in and is still a draft. - Bind the credential. A person points the destination at a connection
(
POST .../destinations/:name/bind,egress:admin). The host is added through the egress-host routes and the credential through the connection routes;bindtakes ids, never a URL or a secret. - Go live.
state: enabledis its own act,pipeline.destination.enable, and asks again. It needs a cut, an allow-listed host and (for an HTTP webhook) a credential.
Changing one
POST .../destinations/:name/update and the destinations_update tool take exactly one change.
The act is derived from the difference between the destination as it is and the one you ask for,
never from an argument.
| Change | Act | Risk | Applies |
|---|---|---|---|
state: paused |
pipeline.destination.pause |
ELEVATED | Allowed. SENSITIVE and asked when the target carries alert, monitor, SLO or status events. |
state: enabled from a pause |
pipeline.destination.resume |
SENSITIVE | Asked. Releases what the pause held. |
state: enabled from a draft |
pipeline.destination.enable |
SENSITIVE | Asked (ask floor). |
| Fewer fields, a stricter tier, a tighter filter | pipeline.destination.narrow |
ELEVATED | Allowed under a policy; needs a preview digest. |
| A pace change | pipeline.destination.update |
SENSITIVE | Asked (ask floor). |
suppression |
pipeline.suppression.create |
ELEVATED | Allowed. Stops one subject's rows. |
replay |
pipeline.delivery.replay |
SENSITIVE | Asked; CRITICAL with dual control when the target changed since the first attempt or the range exceeds 30 days. See the note below. |
What an agent can never do
A change that lets more leave, or leave somewhere else, is pipeline.destination.widen: a
person's act with egress:admin. The governed path refuses it before anyone is asked, naming the
act. Concretely, all of these are widenings:
- a field added;
- a lower tier (
agenttostored); - any change of host or request path;
- a filter that is not provably narrower (it narrows only if it keeps every clause the old one had; a reworded clause is a widening);
- dropping a rule that protected a field.
A mixed change (one field removed, another added) is a widening. The never-widen property test runs
thousands of random plans over all five dimensions and asserts that nothing the family would let an
agent apply holds less back than before. A new destination is born at the agent tier; choosing
stored is a person's act too.
Deleting a destination, removing a suppression, adding a host and setting a credential are human-only and have no tool. They are refused to an agent, a service and an OAuth-client human, and each writes one audit row.
Suppressions
A suppression stops one subject's rows reaching one destination. The key you give is an opaque
pseudonym; an email address, a phone number or a sentence is refused. It is stored and echoed only
as a keyed hash (an HMAC under the deployment's secret and your organization), so a stored row, a
plan, an operation record and every answer carry the hash and nothing that was typed. No tool returns
even the hash: destinations_list returns a count. A person with pii:read sees the hashes in
the dashboard (GET .../suppressions). Removing one is consent loosening and is a person's act.
Existing webhooks and sinks
Every outbound webhook and warehouse sink gets exactly one umbrella destination row (an additive
backfill, idempotent, named umbrella-webhook-... or umbrella-sink-..., a name space customers
cannot take), so pause, a field list and the delivery ledger cover them too.
- Pausing the umbrella pauses the real thing. The pause is written under the webhook's or sink's own ledger key, the one the sender reads, and the webhook's delivery pass skips it.
- A field list on a webhook umbrella cuts the
dataof each body to those paths and scrubs it at the row's tier at send time, and the signature covers the bytes that left. With no list the body is sent exactly as stored; setting one is a narrowing, clearing it is a widening.
Tools
| Tool | Relation | What it does |
|---|---|---|
destinations_list |
read (preview: configure_pipeline, held) |
The destinations a project sees, with rules, deliveries and the preview on request. Suppressions as counts. Names, hosts, field paths and payload rows are fenced and untrusted. |
destination_propose |
configure_pipeline (held) |
The governed create. Always asks. |
destinations_update |
configure_pipeline (held) |
The governed change, the act derived from the diff. |
All three are in the pipeline toolset. The write tools are held until the security review of the
OAuth authorization server is signed off: they are not listed for any token a production path can
mint, and the engine repeats the check.
Notes for operators
- Replay of dead batches is implemented and tested, but its act (
pipeline.delivery.replay) is not yet registrable with the engine: the registry requires an irreversible act to be CRITICAL as a class, and this one is SENSITIVE with a CRITICAL derivation. Until that registry row changes, the replay doors answerreplay_not_registered, and a person resumes a paused destination to release what was held. - A preview digest expires in 10 to 15 minutes. The check runs again when the approved change is
retried, so an approval that takes longer than that is refused with
preview_expiredand applies nothing (the yes is not spent); preview the change again and propose it again. object_storedestinations share the model and the governance; their delivery rides the customer-bucket export sink and is not part of the HTTP delivery pass yet.