Skip to content
bucker

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:

  1. 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).
  2. 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.
  3. The cut: only the allow-listed paths survive. It comes after the rules, because a set or rename rule can introduce a field, and a field nobody allow-listed must not leave.
  4. The scrub at the destination's tier, with your organization's own scrub rules.
  5. 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

  1. Preview. POST .../destinations/preview, or destinations_list with include: [preview] and a candidate. 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_available until 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.
  2. Propose. POST .../destinations or the destination_propose tool, with that digest. The act is pipeline.destination.create, which always asks. The destination is filled in and is still a draft.
  3. 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; bind takes ids, never a URL or a secret.
  4. Go live. state: enabled is 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 (agent to stored);
  • 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 data of 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 answer replay_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_expired and applies nothing (the yes is not spent); preview the change again and propose it again.
  • object_store destinations share the model and the governance; their delivery rides the customer-bucket export sink and is not part of the HTTP delivery pass yet.