Skip to content
Registry StackDocsv0.34.0
Search

Send registry events to a webhook

For the data publisher

View as Markdown

This tutorial uses the maintained Base Registry Engine (BReg) business demo and the receiver supervised by bregctl dev. You will read the event declaration, create a record, and inspect the value-redacted delivery receipt.

Outcome
One signed CloudEvents delivery caused by your authenticated write, with a receipt from the supervised receiver.
Time
About 15 minutes
Level
Local evaluation only
Prerequisites
DockerPython 3Rust and Cargo, or installed breg and bregctl binariescurl 7.76 or laterTwo terminals

Start the demo receiver

Section titled “Start the demo receiver”

From the Registry Stack checkout, run:

Terminal window
products/breg/demo/run.sh --webhook

The launcher creates a disposable project under products/breg/demo/.run, starts PostgreSQL, the stock ThunderID issuer, Base Registry Engine, and the loopback receiver. Leave it running in this terminal.

Read the declaration

Section titled “Read the declaration”

In another terminal:

Terminal window
webhook_run="$PWD/products/breg/demo/.run"
grep -A20 '^    hooks:' \
  "$webhook_run/project/modules/business-establishment-summary/module.yaml"

The operating-created-v1 event selects the establishment entity, the created trigger, and the projected establishment-code and operating-status values. The compiled destination binding, retry policy, and disclosure can be inspected without opening runtime secrets:

Terminal window
bregctl explain events "$webhook_run/project"

Cause a delivery

Section titled “Cause a delivery”

Acquire a fresh token through the retained dev session and copy its protected header file:

Terminal window
umask 077
bregctl --format json dev token business-demo "$webhook_run/project" \
  > tutorial-work/webhook-token.json
python3 -c 'import json,shutil,sys; shutil.copyfile(json.load(open(sys.argv[1]))["headerFile"], sys.argv[2])' \
  tutorial-work/webhook-token.json tutorial-work/webhook-authorization.header
chmod 600 tutorial-work/webhook-authorization.header

Create an operating establishment:

Terminal window
webhook_url=$(cat "$webhook_run/breg-origin")
curl --silent --show-error --fail-with-body \
  --header @tutorial-work/webhook-authorization.header \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: tutorial-establishment-9' \
  --data '{"data":{"establishmentCode":"ESTABLISHMENT-TUTORIAL-009","siteName":"North Quay Annex","establishmentKind":"warehouse","operatingStatus":"operating"}}' \
  --output tutorial-work/establishment.json --write-out 'HTTP %{http_code}\n' \
  "$webhook_url/v1/records/establishments?accessProfile=business-operator"

The response is 201. Delivery runs after the transaction commits, so allow a few seconds before reading the receiver report.

Inspect the receipt

Section titled “Inspect the receipt”
Terminal window
bregctl --format json dev events "$webhook_run/project" \
  > tutorial-work/webhook-events.json
python3 -m json.tool tutorial-work/webhook-events.json

The report identifies the compiled event and destination, generation, attempt, and receipt time. Payloads are omitted unless you explicitly add --include-payload. A receipt means the receiver accepted that attempt. Operated deployments inspect pending and dead-letter work through the separate webhook operations described in Operate BReg webhooks.

Stop the demo

Section titled “Stop the demo”

Press Ctrl+C in the first terminal. A successful run removes its owned dev session. An interrupted or failed run retains .run/ for diagnosis. Stop that owned session before removing the directory and retrying.

Keep tutorial-work/webhook-authorization.header out of support messages. The checkout ignores it, but it remains a bearer credential until it expires.

Troubleshooting

Section titled “Troubleshooting”
SymptomNext move
A request returns 401Rerun bregctl dev token business-demo "$webhook_run/project" while the demo remains active and copy the new headerFile.
The new receipt is not visible yetWait a few seconds and rerun bregctl dev events.
The launcher stops before its ready lineRead the bounded diagnostics it prints. Preserve the failed .run/ directory until you have diagnosed the owned session.

Next

Section titled “Next”