Webhook Event Types | Canopy Docs

Overview

When something changes in Canopy (a role is assigned, an identity is created, a node moves), an event fires. A webhook subscription lists the event types it wants, and Canopy delivers a signed HTTP POST to your endpoint for each matching change. Subscribe to a specific set, or use the wildcard "*" to receive every event in the subscription's scope (including ones added later).

Events come in two scopes

Canopy's data model is two-tiered, so events are too. Environment-scoped events carry an environment_id and cover authorization config (assignments, roles, permissions, and hierarchy nodes), delivered to env-scoped subscriptions. Account-scoped events span environments (identity lifecycle, membership, and sessions), delivered to account-scoped subscriptions. A subscription only receives events from its own scope.

Environment events

Fired by changes to an Environment's authorization configuration. Delivered to environment-scoped subscriptions.

assignment.created: A role was assigned to an identity at a node.

assignment.updated: An existing role assignment was updated.

assignment.removed: A role assignment was removed from an identity.

assignment.bulk_created: Multiple role assignments were created in one operation.

assignment.bulk_removed: Multiple role assignments were removed in one operation.

assignment.bulk_role_changed: The role on multiple assignments was changed in bulk.

role.created: A role was created.

role.updated: A role's name or metadata was updated.

role.deleted: A role was deleted.

role.permissions.updated: The permissions attached to a role were changed.

permission.created: A permission was created.

permission.updated: A permission was updated.

permission.deleted: A permission was deleted.

node.created: A hierarchy node was created.

node.updated: A hierarchy node was updated.

node.deleted: A hierarchy node was deleted.

node.moved: A hierarchy node was moved, changing inheritance.

hierarchy_schema.updated: The hierarchy node-type schema was updated.

Account events

Account-scoped events span environments, because identities live at the Account level. Delivered to account-scoped subscriptions.

identity.created: An identity was created.

identity.updated: An identity's profile or attributes were updated.

identity.removed: An identity was removed.

identity.status_set: An identity was activated or deactivated.

identity.erased: An identity's personal data was erased (GDPR/CCPA). The payload carries only the pseudonymous identity id.

identity.env_membership.added: An identity was granted membership to an environment.

identity.env_membership.removed: An identity's environment membership was removed.

account_member.added: A member was added to the account.

account_member.removed: A member was removed from the account.

session.all_revoked: All active sessions for an identity were revoked.

Payloads & the audit log

Every event mirrors an audit-log entry

Webhook event types are the same actions Canopy records in its audit log: every delivery corresponds to an audit entry, so you can reconcile what you received against the authoritative trail and use the audit log to replay anything an endpoint missed. The live list of subscribable event types for a scope is also available from the API at GET …/webhooks/event-types, so your integration can validate against it programmatically.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.