> For the complete documentation index, see [llms.txt](https://help.cerby.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.cerby.com/developer-tools/cerby-webhooks/webhook-events-for-account-ownership-transfer.md). # 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. {% hint style="info" %} **Who can use this feature?** * Workspace **Owners**, **Super Admins**, and **Admins** * Supported using the Cerby web app and the Cerby API {% endhint %} 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](/developer-tools/cerby-webhooks/implement-a-webhook-receiver.md). {% hint style="danger" %} **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. {% endhint %} ## 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. {% hint style="info" %} **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. {% endhint %} ## 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. {% hint style="danger" %} **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. {% endhint %} ## 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](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook) and [Edit a webhook](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/edit-a-webhook). ## Related articles **Developer reference:** * [Implement a webhook receiver](/developer-tools/cerby-webhooks/implement-a-webhook-receiver.md) * [Handle breach detection events](/developer-tools/cerby-webhooks/webhook-events-for-credential-breach-detection.md) **Feature guides:** * [Explore webhook notifications](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications) * [Create a webhook](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook) **Troubleshooting:** * [Troubleshooting: Webhook deliveries failing](https://help.cerby.com/tips-and-troubleshooting/troubleshooting/webhooks/troubleshooting-webhook-deliveries-failing) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.cerby.com/developer-tools/cerby-webhooks/webhook-events-for-account-ownership-transfer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.