Switchyard
GitHub
Run the failure demo

Use cases

Workflows where the operational record changes the outcome.

These are not industries. They are recurring situations in webhook operations: a dispute, a go-live, a local bug, a misrouted event, an agent that needs facts, an incident with too many screenshots. Each one ends with an artifact you can hand to someone.

Delivery is at least once; duplicates remain possible. The workflows below depend on the record Switchyard preserves, not on a delivery guarantee.

Workflow 01 — Customer escalation

Move the ticket from dispute to evidence.

The provider says delivered. The customer says nothing happened. Both are looking at partial records.

Support engineer on an escalation

Triggering situation
The provider dashboard shows delivered. The customer insists nothing arrived. The ticket is now an argument.
Existing workaround
Ask engineering to grep application logs and compare timestamps by hand.
Why it fails
Logs show the receiver's side only. They lack the exact request bytes, the signature check, and the delivery attempts — so the dispute continues.
Switchyard workflow
Open the preserved event. Check the verification status and the delivery trail: every attempt, response status, and error class. Export the sanitized receipt and attach it to the ticket.
Concrete proof/output
A sanitized receipt showing what arrived, where it was routed, and how each delivery attempt ended — evidence both sides can read.

Escalation path

  1. Provider reports delivered; customer reports nothing.
  2. Open the preserved event — request kept as it arrived.
  3. Read verification status and the full delivery trail.
  4. Export the sanitized receipt and attach it to the ticket.
Artifact
Sanitized receipt — raw bodies, header values, and secret material are structurally absent.
Inspect a sample receipt Sample data. Not from a customer or production incident.

Workflow 02 — Pre-launch validation

Prove the integration before production traffic starts.

A passing smoke test proves one happy path. Go-live evidence has to cover verification, routing, failure, and recovery.

Implementation engineer before go-live

Triggering situation
A customer integration must be proven before production traffic starts.
Existing workaround
Send a few test webhooks and eyeball the receiver logs.
Why it fails
A happy-path test says nothing about signature verification, routing selection, or what happens when the receiver fails.
Switchyard workflow
Verify the signature. Run the routing dry run. Deliver to the destination. Break the receiver, watch retries run to exhaustion, repair it, replay the event, and export the receipt.
Concrete proof/output
A receipt export that records verification, routing, failure, repair, and a successful replay — go-live evidence, not a screenshot.

Validation sequence

  1. Signature verification returns a status from the fixed vocabulary.
  2. Routing dry run shows the selected destination before any delivery.
  3. Delivery runs; a forced receiver failure exhausts retries.
  4. Repair the receiver and replay the preserved event.
  5. Replay succeeds; export the receipt as go-live evidence.
Artifact
Receipt export covering the full sequence, tied to one event ID.
Run the failure demo

Workflow 03 — Local reproduction

Get the real provider event onto localhost.

Private-network delivery uses the authenticated relay. The preserved source event comes to your machine; you do not re-trigger the provider.

Engineer debugging a handler locally

Triggering situation
A handler fails on a real provider event, and you need that exact event on localhost.
Existing workaround
Re-trigger the provider, or paste a saved payload into a local curl command.
Why it fails
Re-triggering creates a new event with new state. A pasted payload may not match the headers and signature the handler actually received.
Switchyard workflow
Point the authenticated relay at the endpoint and at your local server. The preserved source event is delivered to localhost — the same event, not a fresh trigger.
Concrete proof/output
The original event lands on http://localhost:3000 with a delivery attempt recorded against the same event ID.

Relay path

shell 
switchyard relay --endpoint ENDPOINT --to http://localhost:3000
Artifact
Relay delivery recorded against the original event ID.
Start the quickstart

Workflow 04 — Routing investigation

Answer which configuration was active.

The event arrived but went to the wrong destination — or nowhere. The current config is not the config that made the decision.

On-call engineer tracing a misrouted event

Triggering situation
An event arrived but went to the wrong destination, or matched nothing at all.
Existing workaround
Diff the current routing config against what you remember deploying.
Why it fails
The current config is not the config that decided. Without the active version, 'what changed' is guesswork.
Switchyard workflow
Open the routing explanation. The immutable rule_set_version names the configuration that was active. The explanation lists the selected destination and every skipped one.
Concrete proof/output
A routing explanation with a rule_set_version, a selected destination, and the reasons the others were skipped.

Routing explanation, drawn as rails

Artifact
Routing explanation — selected and skipped destinations under an immutable rule_set_version.
Inspect the architecture

Workflow 05 — AI-assisted diagnosis

Give the agent facts and a fence, not secrets and a shell.

AI can reason over the evidence. It does not become the evidence. Operations stay scoped; facts stay separate from inference.

Engineer handing diagnosis to an agent

Triggering situation
You want an agent to help diagnose a failed delivery.
Existing workaround
Paste logs and environment dumps into the prompt and hope the secrets stay out.
Why it fails
Unstructured fragments mix facts with guesses, and pasted material can carry tokens, raw bodies, and signature values.
Switchyard workflow
Issue a scoped token — events:read deliveries:read deliveries:operate receipts:read. The agent reads typed, sanitized facts and bounded follow-up operations: event replay, delivery retry, delivery wait, events wait.
Concrete proof/output
A diagnosis grounded in preserved facts, with every action inside the token's scope — never raw secrets, never arbitrary shell.

What the agent can see

Verification status is one of a fixed vocabulary:

  • valid
  • invalid
  • missing
  • stale
  • malformed
  • not_configured
  • not_supported
  • unavailable

Allowed follow-up operations:

  • event replay
  • delivery retry
  • delivery wait
  • events wait
Artifact
Scoped token — e.g. events:read deliveries:read deliveries:operate receipts:read.
See the evidence shape

Workflow 06 — Shared incident evidence

One artifact for support, implementation, and engineering.

Three teams working the same incident from three tools produce three versions of the story. A bundle produces one.

Support, implementation, and engineering on one incident

Triggering situation
Three teams work the same incident from three different tools.
Existing workaround
Screenshots in tickets, log excerpts in chat, and a summary doc that drifts.
Why it fails
Each artifact is a copy. Copies diverge, leak raw data, and expire from memory before the incident closes.
Switchyard workflow
Build one incident bundle — up to 20 events with their sanitized receipts — and share it through an expiring, revocable evidence share. The same artifact attaches to tickets and PRs.
Concrete proof/output
One immutable bundle everyone references; access expires and can be revoked when the incident closes.

Bundle lifecycle

  1. Select the events that belong to the incident — at most 20.
  2. Bundle them with sanitized receipts; the bundle is immutable.
  3. Share through an evidence share with an expiry.
  4. Attach the same artifact to the ticket and the PR.
  5. Revoke access when the incident closes.
Artifact
Incident bundle plus an expiring, revocable evidence share.
Inspect the evidence model

Run the failure demo.

Step through a real failed delivery — capture, routing, exhaustion, repair, replay, receipt — then run the same loop on your own machine.

Run the failure demo Start the quickstart Read the trust page

The demo uses sample data. The quickstart runs a local instance you control.