---
title: "Events, metadata, and backend integration"
description: "Follow instance events, verify webhook deliveries, update declared metadata, and onboard a Squads proposer."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

> For the complete documentation index optimized for AI agents, see [llms.txt](https://docs.arete.run/llms.txt) or [llms-full.txt](https://docs.arete.run/llms-full.txt). A markdown version of this page is available at [/integrating-protocols/events.md](https://docs.arete.run/integrating-protocols/events.md) or by sending `Accept: text/markdown`.
Use events to keep an application current and trigger your own backend work.
Use canonical reads with your credentials to fetch the details needed by that
work, rather than assuming an event contains the full instance.

## Follow an instance

```ts
const subscription = client.events(instanceId, {
  onEvent(event) {
    console.log(event);
  },
  onError(error) {
    console.error(error);
  },
});
// When this view or worker is disposed:
subscription.close();
```

The client reconnects and resumes after the last event id. You can supply
`lastEventId` when starting a subscription. Treat a stream event as a reason
to refresh the affected state; a displayed live row is not an execution result.

React users can use `useProtocolEvents` or the
[instance hooks](/integrating-protocols/react/).

## Receive named emissions through webhooks

A protocol's `emit` reactions publish named events. Configure an endpoint
subscription for the required event names with the protocol owner. Webhooks
are signed POST deliveries; process only verified requests.

```ts
import { verifyWebhook } from "@usearete/sdk";

const rawBody = await request.text();
const verified = verifyWebhook(webhookSecret, rawBody, request.headers);
```

Verify the raw bytes before parsing or reserializing them. The verifier checks
signature and timestamp tolerance (five minutes by default). Keep the endpoint
secret on your server. Use the stable delivery `verified.id` to deduplicate
retries. Payloads carry identifiers and state; read further details with your
own authenticated client.

Generated protocol modules also export a typed webhook verifier. See their
`README.md` for the exact generated name. Deliveries can retry: make downstream
work idempotent. Your backend owns notifications, email, and external business
logic.

To run protocol steps for users when an event arrives, for example refunding
everyone who opted in when a raise fails, use `automations.webhookHandler`
from `@usearete/automations`. It verifies, records and deduplicates
deliveries for you. See [Automate steps for users](/automations/overview/).

## Update declared metadata

```ts
const metadata = client.metadata.instance(instanceId);
const current = await metadata.get();
```

Use `metadata.update(patch)` only for fields your credentials may write.
A participant-writer update also takes a wallet proof; construct the exact
message using the handle's `proofMessage`, sign it, and pass `walletProof` in
the update options. Inspect generated schemas for writable fields and types.
Metadata is off-chain application data, separate from transaction settlement.

## Onboard Squads when required

For protocols with multisig administration, the multisig in the deployment
config must be attached to your account and active. Set it up on the
dashboard ([app.arete.run/dashboard/squads](https://app.arete.run/dashboard/squads)),
which works with any browser wallet, or in the Squads app (add the proposer as
a member with the Initiate permission only). From code, use the Arete setup
helpers of the Squads v4 program SDK (`a4 install program squads-v4`); the
member's wallet signs. A deployment refused with
`protocol-squads-setup-required` carries the multisig's dashboard link in
`details.setupUrl`. Per deployment, `client.squads.proposer()` and
`status(multisig)` report the proposer and whether it is an
Initiate-only member.

Arete can propose the declared admin action; it does not vote or execute the
multisig proposal. Handle missing-proposer events as an onboarding requirement,
not as evidence that the admin step completed.