Handle account ownership transfer events

This article describes how to handle the account ownership transfer webhook event, including the fields it carries and why a transfer does not revoke the previous owner's access.

Cerby sends the account.access.ownership_transferred webhook event when an administrator offboards a user and ownership of that user's accounts moves to an incoming owner. It helps you keep your own access records aligned with Cerby by reporting who owned the account before and after the change.

Who can use this feature?

• Workspace Owners, Super Admins, and Admins

• Supported using the Cerby web app and the Cerby API

This event is one of the event types you can subscribe to when you create a webhook. For the envelope structure, signature verification, and delivery guarantees that apply to every Cerby event, refer to Implement a webhook receiver.

IMPORTANT: An ownership transfer adds the incoming owner without removing the departing owner. The departing user keeps ownership of the account and the access that ownership carries, so they normally appear in both owner_ids_before and owner_ids_after. Removing them is a separate administrative step someone must perform deliberately, and no later event reports that removal. If your offboarding process treats an ownership transfer as evidence that the previous owner lost access, it is incorrect. Reconcile the account's owners yourself.

Event payload

The following table describes the data fields this event carries:

Field	Type	Description
account_id	string	The account whose ownership moved, as 32-character undashed hexadecimal.
owner_ids_before	array of strings	The account's user owners read before the change, each as 32-character undashed hexadecimal. Sorted.
owner_ids_after	array of strings	The account's user owners read after the change, each as 32-character undashed hexadecimal. Sorted.
requestor_id	string	The administrator who performed the offboarding, as 32-character undashed hexadecimal.

This event carries no error object.

When this event fires

This event fires only from administrator offboarding, and only for accounts whose sole owner is the user being offboarded. Cerby covers at most 20 accounts per offboarding request.

Ownership changes made any other way do not produce this event. A change made through the change-role flow surfaces as account.access.role_changed instead.

The following conditions also apply:

• A collaborator grant precedes the transfer. When the incoming owner had no access to the account before the transfer, which is the usual case, Cerby first sends an account.access.shared_with_user event with role: account_collaborator for that user. Expect both events.

• The administrator can be the departing owner. Cerby permits an administrator to offboard their own account, so requestor_id can name the same user who is losing sole ownership. Do not assume the two are always different.

• Ownership held through a team or an organization never reaches this flow. The sole-owner check counts a team or an organization as an owner, so an account owned that way never qualifies as solely owned by the departing user.

Reading the owner lists

Both lists are observed readings taken before and after the change, not a computed difference. Compare the two lists rather than assuming what changed.

Both lists name individual users, never a team or an organization. That includes users who own the account indirectly through a collection they belong to, not only users granted ownership directly.

NOTE: Treat the lists as Cerby's best reading of the account's owners rather than a guaranteed-complete roster. If Cerby cannot read an individual owner, it drops that owner from the list and still sends the event, and nothing on the envelope distinguishes a complete list from one missing a dropped owner. If Cerby cannot read the owner set at all, it sends no event rather than an empty list.

Delivery behavior

The ownership change and the event write are separate operations, so ownership can change with no event delivered. Never treat the absence of this event as proof that no transfer happened.

Events that are delivered follow the standard at-least-once policy, so deduplicate on event_id or X-Cerby-Delivery as you would for any other event type.

IMPORTANT: This event sends account_id as 32-character undashed hexadecimal, while account.access.role_changed and account.access.revoked can send the same account as a dashed 36-character UUID. Normalize identifiers before you join or compare them across event types, and do not rely on delivery ordering between them.

Subscribing to this event

You can subscribe to this event individually when you create or edit a webhook, or include it by selecting the Audit-only or Everything preset.

For the steps to subscribe, refer to Create a webhook and Edit a webhook.

Related articles

Developer reference:

• Implement a webhook receiver

• Handle breach detection events

Feature guides:

• Explore webhook notifications

• Create a webhook

Troubleshooting:

• Troubleshooting: Webhook deliveries failing