Business account webhooks

Business account events fire under the businessAccount.* namespace. Business accounts group members, signers, and wallets under one account; these events cover changes to the account itself and to who can act on it. For the shared event envelope, endpoint setup, retries, and signature verification, see Setting up webhooks and Event delivery & best practices. The current list of event types is always available from the event types endpoint.

Account and membership

object

Occurs whenever a business account is created.

object

Occurs whenever a member is added to a business account. Carries the member’s role.

object

Occurs whenever a member’s role changes. Carries the new role.

object

Occurs whenever a member is removed. Removing a member also revokes their key shares, so this is followed by one businessAccount.signer.revoked event for each wallet they signed on.

object

Occurs whenever ownership moves to another member. Carries both the previous and the new owner.

object

Occurs whenever a member gains a key share on one of the account’s wallets, making them a signer.

object

Occurs whenever a signer’s key share on a wallet is revoked. Also sent for each signer severed by a member removal or a wallet unlink.

object

Occurs whenever a wallet comes under the account’s control.

object

Occurs whenever a wallet leaves the account. Every signer on that wallet loses their key share, so this is accompanied by a businessAccount.signer.revoked event for each.

businessAccount.updated is emitted when the account’s own details change, such as its name, but is not selectable in the event types catalog today.

Governance and roles

An account’s governance section holds the approval rules, and its roles decide what a member can do. Both live in the account’s signed document rather than in a record you can read back, so these three events carry the resulting document version.

object

Occurs whenever the approval rules change. Carries governedActions, the list of actions that now have a rule, and not the rules themselves (a rule names the users and roles that can approve). Read the governance section through the API to get the new rules.

object

Occurs whenever a custom role is defined. Carries the role name and inherits, the built-in role it takes its permissions from.

object

Occurs whenever a custom role is deleted. A role cannot be deleted while a member still holds it, so no member loses access as a result.

Approvals

An account can require approvals before a change applies. A change that needs them does not take effect immediately: a proposal opens, collects approvals, and applies once its requirements are met. These five events cover that lifecycle.

An approved change sends two events: the proposal event below, and the ordinary account event for the change itself. A governed member removal sends both businessAccount.proposal.executed and businessAccount.member.removed. Subscribe to the family you need: the proposal events for approval workflow, the account events for keeping your own records in step.

object

Occurs whenever a change needs approvals and a proposal opens. Carries who to ask, and how many people are needed.

object

Occurs whenever an approval is recorded. Carries the approver and the time they signed.

object

Occurs whenever an approver takes back an approval they had given. This is the only proposal event that lowers the count, so a reader that tracks progress must handle it: a proposal can fall back below its requirements after it had met them.

object

Occurs whenever a proposal is refused. A veto is final, whatever approvals the proposal already holds.

object

Occurs whenever a proposal meets its requirements and the change applies.

Reading a proposal payload

quorum answers what the change needs. dependencies answers why, one entry per governance rule that applies.

Do not add up the approvalsRequired values in dependencies. One approval counts toward every rule its approver is eligible for, so the total overstates what is needed. Use quorum.effectiveRequiredApprovals, which is the number of people the change actually needs.

{
  "proposalId": "prp_9f3c",
  "businessAccountId": "ba_acme",
  "action": "removeMember",
  "status": "awaitingApproval",
  "initiatorUserId": "usr_lee",
  "targetUserId": "usr_dana",
  "completeBy": "2026-10-14T18:22:40.881Z",
  "changeSet": [{ "type": "removeMember", "userId": "usr_dana" }],
  "quorum": {
    "effectiveRequiredApprovals": 2,
    "governingDependency": "offboard-dual-control",
    "approvedBy": [],
    "eligibleApprovers": ["usr_ray", "usr_kim", "usr_max", "usr_nia"],
    "mandatoryApproverRoles": ["compliance"]
  },
  "dependencies": [
    {
      "id": "offboard-dual-control",
      "requirementId": "offboard-dual-control",
      "changeType": "removeMember",
      "target": { "userId": "usr_dana" },
      "derived": false,
      "approvalsRequired": 2,
      "approvedBy": [],
      "satisfied": false,
      "eligibleApprovers": ["usr_ray", "usr_kim", "usr_max", "usr_nia"],
      "mandatoryApproverRoles": ["compliance"]
    },
    {
      "id": "share-revocation:wlt_treasury",
      "requirementId": "share-revocation",
      "changeType": "removeSignerFromWallet",
      "target": { "userId": "usr_dana", "walletId": "wlt_treasury" },
      "derived": true,
      "approvalsRequired": 1,
      "approvedBy": [],
      "satisfied": false,
      "eligibleApprovers": ["usr_ray", "usr_kim", "usr_max"]
    }
  ]
}

Three fields repay a closer look:

changeSet holds only what the person asked for. Removing a member also revokes their key shares, and those extra changes appear as dependencies with derived: true rather than in changeSet.
eligibleApprovers can differ between dependencies. A rule limited to people who hold a key share on a particular wallet admits fewer people than a rule that is not. Send each person the dependency they can actually act on.
id is unique within the payload; requirementId is the rule’s name from the account’s own configuration. One rule applied to two wallets produces two dependencies that share a requirementId, so use id as the key.

Learn

Implement

Business account webhooks

Account and membership

Governance and roles

Approvals

Reading a proposal payload

​Account and membership

​Governance and roles

​Approvals

​Reading a proposal payload

Account and membership

Governance and roles

Approvals

Reading a proposal payload