Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Send registry events to a webhook

> Run the business demo with its supervised receiver, cause a signed CloudEvents delivery, and inspect the receipt without exposing credentials.

import QuickstartMeta from '../../../components/QuickstartMeta.astro';

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.

<QuickstartMeta
  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={['Docker', 'Python 3', 'Rust and Cargo, or installed breg and bregctl binaries', 'curl 7.76 or later', 'Two terminals']}
/>

## Start the demo receiver

From the Registry Stack checkout, run:

```sh
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

In another terminal:

```sh
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:

```sh
bregctl explain events "$webhook_run/project"
```

## Cause a delivery

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

```sh
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:

```sh
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

```sh
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](../../operate/breg-webhooks/).

## 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

| Symptom | Next move |
| --- | --- |
| A request returns `401` | Rerun `bregctl dev token business-demo "$webhook_run/project"` while the demo remains active and copy the new `headerFile`. |
| The new receipt is not visible yet | Wait a few seconds and rerun `bregctl dev events`. |
| The launcher stops before its ready line | Read the bounded diagnostics it prints. Preserve the failed `.run/` directory until you have diagnosed the owned session. |

## Next

- [Author a registry project](../../configure/breg/) to declare events on your own entities.
- [Operate BReg webhooks](../../operate/breg-webhooks/) to configure operated destinations, retry limits, and dead-letter recovery.
- [Base Registry Engine API reference](../../reference/breg-api/) for the delivery contract a receiver validates and deduplicates.