Send registry events to a webhook

In about fifteen minutes your registry will tell another system each time a contact is created: the event declared, a contact added, and the signed delivery read back from a local receiver.

Outcome

A signed contact-created delivery received by the local receiver.

Time

About 15 minutes

Level

Local evaluation only

Prerequisites

The project from Extend a registry with a moduleRunning DockerAn editor

Declare the event

In the project directory, ask which events the registry sends today:

bregctl explain events .

Event deliveries:
  No event deliveries declared.

None: a registry sends nothing until a Record type declares it. Open registry.yaml and add a hooks list to the contact Record type, right after its mutationMode line:

registry.yaml

mutationMode: mutable
hooks:
  - id: contact-created-v1
    phase: after
    trigger: created
    projection: [name]
    handler:
      type: url
      destinationId: contact-events

The hook fires once a new contact is committed. Its projection lets only name leave the registry. contact-events is a destination name, not an address: an operator binds it to a URL, and the local registry binds it to a receiver of its own.

Check the project and ask again:

bregctl check .
bregctl explain events .

Event deliveries:
  events.contact.contact-created-v1.webhook
    phase         after
    handler type  url
    destination   contact-events
    projected fields  name

Create a contact

Start the registry with the hook in place:

bregctl dev start

webhook receiver  http://127.0.0.1:<port>/events
events file       <project-dir>/.breg/dev/events.jsonl

The receiver verifies each delivery’s signature before it keeps it, in .breg/dev/events.jsonl. That file holds projected values, so use test records only. Add the test contact again:

bregctl examples run contact

The registry commits the contact first, then delivers the event from its own queue.

Read the delivery

bregctl --format json dev events

{
  "deliveryId": "events.contact.contact-created-v1.webhook",
  "destinationId": "contact-events",
  "eventType": "contact-created-v1",
  "attempt": 1,
  "status": "received"
}

"status": "received" means the receiver verified the signature and kept the first attempt. The report leaves out the projected name; add --include-payload to see it.

If deliveries is empty, the first delivery has not arrived yet or the registry is still retrying; run the command again after a few seconds. On a deployed registry, bregctl webhook list shows the deliveries still waiting or failed, as Bind webhook receivers describes.

The local receiver proves only that an attempt arrived. A real receiving service stores each event before acting on it. A retry resends an event with the same idempotencyKey; an operator replay resends it with the same eventId and a new key. Check both before acting.

When you are finished, bregctl dev stop --remove stops the registry and deletes its test data.

Next

Serve a lookup to Evidence, or run a registry for real with Deploy and serve.