Simulators

Boot seed files

A boot seed file declares your app’s webhook before the first request, with the signing secret your app already verifies with. Start the simulator with --seed naming the file, or in a container with RYSTIC_SEED. A value written {"$env": "NAME"} takes the simulator’s environment variable NAME:

echo '{"state_webhook": {"4dd369bc-aa82-4ff3-97de-514ae3000ee0": {"id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0", "object": "webhook", "endpoint": "http://app:3000/api/webhooks/resend", "events": ["email.sent", "email.bounced"], "signing_secret": {"$env": "RESEND_WEBHOOK_SECRET"}, "status": "enabled", "created_at": "2026-01-01 00:00:00.000+00"}}}' > seed.json
export RYSTIC_URL=$(rystic run resend-twin -d --port 0 --name seeded --seed seed.json --env RYSTIC_WEBHOOK_DELIVERY=on --env RESEND_WEBHOOK_SECRET=whsec_c2VjcmV0LWZvci1teS1hcHA= --json | jq -r .data.url)
curl -s "$RYSTIC_URL/webhooks/4dd369bc-aa82-4ff3-97de-514ae3000ee0" -H 'Authorization: Bearer re_placeholder' | jq -c '{endpoint, status, signing_secret}'
# -> {"endpoint":"http://app:3000/api/webhooks/resend","status":"enabled","signing_secret":"whsec_c2VjcmV0LWZvci1teS1hcHA="}

What stops the simulator at startup

The simulator refuses a seed file it cannot load as written, and its message says where in the file:

The seed file has	Refused
`{"$env": "NAME"}` with `NAME` unset or empty	always
`{"$env": "NAME"}` where `NAME` is not a variable name or is one of the simulator’s own `RYSTIC_` settings	always
a key repeated within one object	always
an enabled webhook without an absolute `http` or `https` `endpoint`	with `RYSTIC_WEBHOOK_DELIVERY=on`
an enabled webhook whose `signing_secret` is missing, empty or not base64 after an optional `whsec_` prefix	with `RYSTIC_WEBHOOK_DELIVERY=on`

Started with a secret that is not base64, the same file stops the simulator:

rystic run resend-twin -d --port 0 --name badsecret --seed seed.json --env RYSTIC_WEBHOOK_DELIVERY=on --env RESEND_WEBHOOK_SECRET=whsec_not-base64! --json | jq -r .error.message
# -> ...state_webhook/4dd369bc-aa82-4ff3-97de-514ae3000ee0: signing_secret cannot sign a delivery: endpoint secret is not base64...