Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(platform): add Platform Webhooks guide and event catalog (#51098)

Nik Richers6ecf98671a8e
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index 0f7c3bb734a..f20b9443ae4 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -2867,6 +2867,15 @@ export const platform: NavMenuConstant = {
},
],
},
+ {
+ name: 'Platform Webhooks',
+ url: '/guides/platform/webhooks',
+ enabled: fullPlatformEnabled,
+ items: [
+ { name: 'Overview', url: '/guides/platform/webhooks' as `/${string}` },
+ { name: 'Events', url: '/guides/platform/webhooks/events' as `/${string}` },
+ ],
+ },
],
},
{
diff --git a/apps/docs/content/guides/platform/webhooks.mdx b/apps/docs/content/guides/platform/webhooks.mdx
new file mode 100644
index 00000000000..c3b3807ec00
--- /dev/null
+++ b/apps/docs/content/guides/platform/webhooks.mdx
@@ -0,0 +1,312 @@
+---
+id: 'platform-webhooks'
+title: 'Platform Webhooks'
+description: 'Receive HTTP notifications when events occur in your Supabase organization or project.'
+---
+
+Platform Webhooks send an HTTP request to a URL you control when something happens on your organization or one of its projects. For example, a project pausing and a member joining both raise events. Use them to build event-driven integrations without polling the Management API.
+
+<Admonition type="note" title="Platform Webhooks is an early access feature">
+
+Platform Webhooks is available to organizations on an early access allowlist. The API rejects a request from an organization outside the allowlist with `403` and the error code `access_disabled`.
+
+</Admonition>
+
+For the complete API reference, see [Organization Webhooks](/docs/reference/api/v2-organizations-slug-webhooks-endpoints-get) and [Project Webhooks](/docs/reference/api/v2-projects-ref-webhooks-endpoints-get) in the Management API reference.
+
+- [Set up an endpoint](#set-up-an-endpoint) creates the configuration that receives events.
+- [Verify webhook signature](#verify-webhook-signature) has the check your listener needs before it trusts a delivery.
+- [Send a test event](#send-a-test-event) triggers a test event to be sent to your listener.
+- [Delivery behavior](#delivery-behavior) covers retries and history retention.
+- [Idempotency and ordering](#idempotency-and-ordering) covers idempotency, duplicates, and arrival order.
+- [Best practices](#best-practices) covers best practices for writing a reliable, resilient webhook listener.
+
+## Concepts
+
+### Endpoints
+
+An _endpoint_ is a configuration for where and how to deliver events. It has a URL, a signing secret, the event types it subscribes to, and optional custom headers.
+
+You register an endpoint against an organization or a specific project within an organization. Each endpoint subscribes to one or more event types, or to `*` to receive all events.
+
+An endpoint is scoped to either an organization or a single project:
+
+- An **organization-scoped** endpoint receives every organization event and every project event across the organization.
+- A **project-scoped** endpoint receives events for that project only.
+
+Endpoint URLs must be publicly reachable and must resolve to a non-reserved IP address.
+
+### Events
+
+An _event_ represents something that happened in your organization or project. Each event has an ID, a type string such as `v1.project.paused`, a timestamp, and a payload.
+
+Each event type starts with a version, for example `v1`, that represents the specific `payload` shape. Different versions of the same event can have different payload shapes.
+
+A project event is delivered to both a matching project-scoped endpoint and any organization-scoped endpoints in the same organization. Each endpoint gets its own copy of the event, with its own `id`.
+
+For the full list of event types and their payloads, see [Platform Webhook Events](/docs/guides/platform/webhooks/events).
+
+### Deliveries
+
+A _delivery_ is one HTTP `POST` attempt for a specific event to a specific endpoint. Supabase records every delivery attempt along with its outcome, response status, and response body.
+
+### Envelope and payload
+
+Every delivery sends a JSON body with the following structure regardless of the type:
+
+```json
+{
+ "id": "<event UUID>",
+ "type": "<event-type>",
+ "timestamp": "<ISO 8601 UTC>",
+ "payload": {
+ "organization_slug": "<org-slug>",
+ "project_ref": "<project-ref>"
+ // event-specific fields
+ }
+}
+```
+
+For example:
+
+```json
+{
+ "id": "01941e0e-e04e-7e43-b8e5-c4d79862b8df",
+ "type": "v1.project.paused",
+ "timestamp": "2025-01-01T12:00:00.000Z",
+ "payload": {
+ "organization_slug": "my-org",
+ "project_ref": "abcdefghijklmnoprstu",
+ "reason": "inactivity",
+ "actor": null
+ }
+}
+```
+
+The `payload` object is event-specific. For organization-scoped events, `project_ref` is always `null`. For details on each event's payload fields, see [Platform Webhook Events](/docs/guides/platform/webhooks/events).
+
+### Versioning
+
+Each event type embeds a version prefix that identifies the payload schema. The `v1` in `v1.project.paused` means the payload follows the version 1 shape for that event. A new version is introduced when the payload changes in a breaking way — fields are removed, renamed, or given a different type.
+
+When Supabase introduces a new version, both versions are emitted simultaneously for a transition period. A handler built for `v1` keeps receiving `v1` events uninterrupted while you add support for `v2`. The transition window is finite, so treat an unrecognized version as a signal to upgrade your handler.
+
+New fields can be added to an existing version without a version bump. Design your handler to ignore fields it does not recognize so that it stays forward compatible within a version.
+
+## Set up an endpoint
+
+Create an endpoint through the Management API:
+
+- To create an organization-scoped endpoint: `POST https://api.supabase.com/v2/organizations/{organization_slug}/webhooks/endpoints`
+- To create a project-scoped endpoint: `POST https://api.supabase.com/v2/projects/{project_ref}/webhooks/endpoints`
+
+An endpoint takes these attributes:
+
+| Attribute | Required | Notes |
+| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url` | Yes | Must use a domain that resolves to a non-reserved IP address. The API rejects a URL that resolves to a reserved range. |
+| `event_types` | Yes | At least one type. An endpoint receives only the types you list. Use `*` to receive every event. |
+| `signing_secret` | Yes | 8 to 64 characters. Every delivery is signed with it. |
+| `custom_headers` | No | Extra request headers. Keys and values are strings, and each has to be a valid HTTP header. |
+| `description` | No | Free text to identify the endpoint. |
+| `enabled` | No | Defaults to `true`. When disabled, events already enqueued get a delivery record with `skipped` status but nothing is sent; events that arrive after disabling are dropped with no delivery record. |
+
+<Tabs scrollable size="small" type="underlined" defaultActiveId="org" queryGroup="scope">
+<TabPanel id="org" label="Organization scoped endpoint">
+
+```bash
+curl -X POST 'https://api.supabase.com/v2/organizations/{your-org-slug}/webhooks/endpoints' \
+ -H 'Authorization: Bearer <personal-access-token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "data": {
+ "type": "endpoint",
+ "attributes": {
+ "url": "https://your-domain.com/webhooks/supabase",
+ "signing_secret": "your-signing-secret",
+ "description": "Track pause and restore events for all projects",
+ "event_types": [
+ { "type": "v1.project.paused" },
+ { "type": "v1.project.restored" }
+ ]
+ }
+ }
+ }'
+```
+
+</TabPanel>
+<TabPanel id="project" label="Project scoped endpoint">
+
+```bash
+curl -X POST 'https://api.supabase.com/v2/projects/{your-project-ref}/webhooks/endpoints' \
+ -H 'Authorization: Bearer <personal-access-token>' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "data": {
+ "type": "endpoint",
+ "attributes": {
+ "url": "https://your-domain.com/webhooks/supabase",
+ "signing_secret": "your-signing-secret",
+ "description": "Track pause and restore events for project <your-project-ref>",
+ "event_types": [
+ { "type": "v1.project.paused" },
+ { "type": "v1.project.restored" }
+ ]
+ }
+ }
+ }'
+```
+
+</TabPanel>
+</Tabs>
+
+To receive all event types, set `event_types` to `[{ "type": "*" }]`. Using `*` also covers event types added in the future, so design your handler to handle unrecognized types gracefully — see [Versioning](#versioning).
+
+A successful request returns `201` with the endpoint's ID, which you can use to send test events, list deliveries, and update or delete the endpoint.
+
+For the full set of operations, see the **Project webhooks** and **Organization webhooks** sections of the [Management API reference](/docs/reference/api/introduction). Every operation exists at both scopes.
+
+## Verify webhook signature
+
+Every delivery follows the [Standard Webhooks](https://www.standardwebhooks.com/) specification and carries these headers:
+
+| Header | Description |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `webhook-id` | The event ID. It's the same across every retry of the same event. |
+| `webhook-timestamp` | The Unix timestamp, in seconds, of when the delivery attempt was signed. |
+| `webhook-signature` | An HMAC-SHA256 signature over `{webhook-id}.{webhook-timestamp}.{raw body}`, in the form `v1,<base64>`. |
+
+Verify against the **raw request body** before you parse it as JSON:
+
+<Tabs scrollable size="small" type="underlined" defaultActiveId="base64" queryGroup="secret-format">
+<TabPanel id="base64" label="Base64 secret">
+
+If your `signing_secret` is a base64-encoded value prefixed with `whsec_`:
+
+```js
+import { Webhook } from 'standardwebhooks'
+
+const webhook = new Webhook(process.env.WEBHOOK_SECRET)
+
+try {
+ const event = webhook.verify(rawBody, {
+ 'webhook-id': req.headers['webhook-id'],
+ 'webhook-timestamp': req.headers['webhook-timestamp'],
+ 'webhook-signature': req.headers['webhook-signature'],
+ })
+ // event is the verified, event.payload can be used
+} catch {
+ return res.status(400).send('Invalid signature')
+}
+```
+
+</TabPanel>
+<TabPanel id="raw" label="Plain string secret">
+
+If your `signing_secret` is a plain string:
+
+```js
+import { Webhook } from 'standardwebhooks'
+
+const webhook = new Webhook(process.env.WEBHOOK_SECRET, { format: 'raw' })
+
+try {
+ const event = webhook.verify(rawBody, {
+ 'webhook-id': req.headers['webhook-id'],
+ 'webhook-timestamp': req.headers['webhook-timestamp'],
+ 'webhook-signature': req.headers['webhook-signature'],
+ })
+ // event is the verified, event.payload can be used
+} catch {
+ return res.status(400).send('Invalid signature')
+}
+```
+
+</TabPanel>
+</Tabs>
+
+For verification libraries in other languages, see the [Standard Webhooks documentation](https://www.standardwebhooks.com/).
+
+To rotate a signing secret without missing deliveries:
+
+1. Add the new secret to your listener, and accept signatures made with either the old or the new secret.
+2. Update the endpoint to use the new secret.
+3. Remove the old secret from your listener.
+
+## Send a test event
+
+Use a test event to verify connectivity end to end. It goes through the same pipeline as a real event and is stored in delivery history, except that automatic retries are disabled.
+
+<Tabs scrollable size="small" type="underlined" defaultActiveId="org" queryGroup="scope">
+<TabPanel id="org" label="For organization scoped endpoint">
+
+```bash
+curl -X POST https://api.supabase.com/v2/organizations/{your-org-slug}/webhooks/endpoints/{your-endpoint-id}/test \
+ -H 'Authorization: Bearer <personal-access-token>' \
+ -H 'Content-Type: application/json' \
+ --data '{
+ "data": {
+ "type": "event",
+ "attributes": { "type": "v1.project.paused" }
+ }
+ }'
+```
+
+</TabPanel>
+<TabPanel id="project" label="For project scoped endpoint">
+
+```bash
+curl -X POST https://api.supabase.com/v2/projects/{your-project-ref}/webhooks/endpoints/{your-endpoint-id}/test \
+ -H 'Authorization: Bearer <personal-access-token>' \
+ -H 'Content-Type: application/json' \
+ --data '{
+ "data": {
+ "type": "event",
+ "attributes": { "type": "v1.project.paused" }
+ }
+ }'
+```
+
+</TabPanel>
+</Tabs>
+
+The event type in the body is optional. Without one, the API uses a type the endpoint subscribes to.
+
+A test event's payload includes `"is_test": true`, so check that field before you trigger any side effect.
+
+## Delivery behavior
+
+Supabase considers a delivery successful when your endpoint returns a `2xx` response within 20 seconds. A non-`2xx` response or a timeout counts as a failure and triggers a retry with exponential backoff:
+
+| Attempt | Wait after the previous failure | Approximate time since the event |
+| --------- | ------------------------------- | -------------------------------- |
+| 1 | Not applicable | Immediately |
+| 2 | 10 seconds | ~10 seconds |
+| 3 | 30 seconds | ~40 seconds |
+| 4 | 1 minute 30 seconds | ~2 minutes 10 seconds |
+| 5 (final) | 4 minutes 30 seconds | ~6 minutes 40 seconds |
+
+After five failed attempts, the delivery is marked as failed with no further retries. Supabase does not notify you when this happens — check delivery history to find permanently failed deliveries.
+
+You can retry a delivery manually. A manual retry is a single attempt: if it fails, no automatic retries follow.
+
+Delivery history is retained for 14 days. An expired delivery is no longer listed and can't be retried.
+
+## Idempotency and ordering
+
+Deliveries are at-least-once: Supabase retries failed deliveries, so your endpoint may receive the same event more than once. Use the `id` field in the request body as a deduplication key. The same `id` always represents the same event.
+
+Deliveries and events may also arrive out of order due to network delays or hiccups. You need to design your webhook listener to account for duplicates and out-of-order events.
+
+## Best practices
+
+Best practices for consuming webhook events and building a reliable, production-grade webhook listener:
+
+- Always verify the webhook signature before processing an event.
+- Check the event type version prefix before processing a payload. For unsupported versions, return `2xx` without processing and log or alert on the unrecognized version — the transition window is finite, so upgrade your handler promptly.
+- Respond to a webhook immediately and process each event asynchronously, for example, on a job queue.
+- Keep track of already processed events in persistent storage to deduplicate them, for example, in a database.
+- Keep track of the last processed event's timestamp and discard stale events of the same type. Do not rely on the order of events.
+- Treat webhook events as a trigger for an action, rather than the state of a resource.
+- Use the webhook's automatic retries as a safeguard against network partitions or timeouts, not as a fallback for listener logic errors.
+- Periodically check delivery history for permanently failed deliveries. Supabase does not notify you when all retries are exhausted.
diff --git a/apps/docs/content/guides/platform/webhooks/events.mdx b/apps/docs/content/guides/platform/webhooks/events.mdx
new file mode 100644
index 00000000000..b83a2b1f644
--- /dev/null
+++ b/apps/docs/content/guides/platform/webhooks/events.mdx
@@ -0,0 +1,447 @@
+---
+id: 'platform-webhook-events'
+title: 'Platform Webhook Events'
+description: 'Event types and payload schemas for Platform Webhooks.'
+---
+
+Webhook events are categorized into two scopes:
+
+- **project events** related to a specific project
+- **organization events** related to the organization itself
+
+For an overview of Platform Webhooks including delivery behavior and signing, see [Platform Webhooks](/docs/guides/platform/webhooks).
+
+<Admonition type="note" title="Platform Webhooks is an early access feature">
+
+Platform Webhooks is available to organizations on an early access allowlist. The API rejects a request from an organization outside the allowlist with `403` and the error code `access_disabled`.
+
+</Admonition>
+
+## Event envelope
+
+Every event arrives in the same envelope regardless of type:
+
+```json
+{
+ "id": "<event UUID>",
+ "type": "<event-type>",
+ "timestamp": "<ISO 8601 UTC>",
+ "payload": {
+ "organization_slug": "<org-slug>",
+ "project_ref": "<project-ref>"
+ // event-specific fields
+ }
+}
+```
+
+For example:
+
+```json
+{
+ "id": "019f3c9c-c758-766d-acb2-94eb089b3f69",
+ "type": "v1.project.paused",
+ "timestamp": "2026-07-07T12:45:35.449Z",
+ "payload": {
+ "project_ref": "your-project-ref",
+ "organization_slug": "your-org-slug",
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+ }
+}
+```
+
+Organization scoped events always have `project_ref` set to `null` because they do not relate to a specific project.
+
+The version prefix in the `type` field, such as `v1`, identifies the payload schema. For how versions change over time and how to handle an unrecognized version, see [Versioning](/docs/guides/platform/webhooks#versioning).
+
+New fields can be added to an existing version without a version bump. Design your handler to ignore fields it does not recognize.
+
+## Common payload fields
+
+### `actor`
+
+Represents a user who performed or triggered an action.
+
+Present on all events. `null` when the event was triggered by an automated system process rather than a user.
+
+```json
+"actor": {
+ "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e"
+}
+```
+
+### `is_test`
+
+Present only on test events sent through the [Send a test event](/docs/guides/platform/webhooks#send-a-test-event) endpoint. Always `true`. Check this field before triggering any side effect.
+
+## Project events
+
+Project events fire when a change occurs or an action is taken in a specific project. The payload always includes both non-nullable `organization_slug` and `project_ref`.
+
+| Event | Fires when |
+| ------------------------------------------------------ | ------------------------------------------------ |
+| [`v1.project.created`](#v1projectcreated) | A project is created |
+| [`v1.project.paused`](#v1projectpaused) | A project is paused |
+| [`v1.project.restored`](#v1projectrestored) | A paused project is restored |
+| [`v1.project.restarted`](#v1projectrestarted) | A project is restarted |
+| [`v1.project.removed`](#v1projectremoved) | A project is deleted |
+| [`v1.project.transferred`](#v1projecttransferred) | A project is transferred to another organization |
+| [`v1.project.status.changed`](#v1projectstatuschanged) | A project's status transitions |
+| [`v1.project.backup.started`](#v1projectbackupstarted) | A project backup begins |
+| [`v1.project.branch.created`](#v1projectbranchcreated) | A preview branch is created |
+| [`v1.project.branch.updated`](#v1projectbranchupdated) | A preview branch is updated |
+| [`v1.project.branch.removed`](#v1projectbranchremoved) | A preview branch is deleted |
+
+### v1.project.created
+
+Fires when a project is created and begins initial setup. When receiving this event, a project might not be healthy yet.
+
+```json
+{
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" },
+ "source": null
+}
+```
+
+`source` is `null` for projects created from scratch. When a project is cloned, `source` carries the origin:
+
+```json
+"source": {
+ "type": "clone",
+ "project_ref": "abcdefghijklmnoprstu"
+}
+```
+
+### v1.project.paused
+
+Fires when a project is paused.
+
+```json
+{
+ "reason": "inactivity",
+ "actor": null
+}
+```
+
+`reason` is one of the following:
+
+| Value | Description |
+| ------------- | ----------------------------------------------------------------------- |
+| `api_request` | Paused by a user via the API or dashboard. `actor` carries the user ID. |
+| `inactivity` | Paused automatically due to inactivity. `actor` is `null`. |
+| `other` | Paused for another system reason. `actor` is `null`. |
+
+### v1.project.restored
+
+Fires when a paused project is restored. When receiving this event, a project might not be healthy yet.
+
+```json
+{
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+### v1.project.restarted
+
+Fires when a project is restarted.
+
+```json
+{
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+### v1.project.removed
+
+Fires when a project is deleted.
+
+```json
+{
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+### v1.project.transferred
+
+Fires when a project is transferred to another organization. A corresponding event is emitted for both the source and the target organizations.
+
+Use `source` and `target` to determine whether the transfer is outgoing or incoming from the perspective of the receiving organization.
+
+```json
+{
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" },
+ "source": { "organization_slug": "from-org" },
+ "target": { "organization_slug": "to-org" }
+}
+```
+
+### v1.project.status.changed
+
+Fires when a project's status transitions.
+
+```json
+{
+ "previous_status": "RESTARTING",
+ "current_status": "ACTIVE_HEALTHY",
+ "actor": null
+}
+```
+
+`previous_status` and `current_status` are one of:
+
+| Value | Description |
+| ------------------ | ------------------------------------ |
+| `ACTIVE_HEALTHY` | Project is running normally |
+| `ACTIVE_UNHEALTHY` | Project is running but has issues |
+| `COMING_UP` | Project is starting |
+| `RESTARTING` | Project is restarting |
+| `RESTORING` | Project is being restored from pause |
+| `RESTORE_FAILED` | Restore operation failed |
+| `PAUSING` | Project is in the process of pausing |
+| `PAUSE_FAILED` | Pause operation failed |
+| `UPGRADING` | Project is being upgraded |
+| `RESIZING` | Project is being resized |
+| `GOING_DOWN` | Project is shutting down |
+| `INIT_FAILED` | Initialization failed |
+| `INACTIVE` | Project is inactive |
+| `REMOVED` | Project has been removed |
+| `UNKNOWN` | Status cannot be determined |
+
+`actor` is `null` for system-initiated transitions. This event fires during normal project operations such as restarts, upgrades, and scaling.
+
+### v1.project.backup.started
+
+Fires when a project backup begins.
+
+```json
+{
+ "actor": null
+}
+```
+
+`actor` is `null` for scheduled backups and carries a `user_id` when the backup is triggered manually.
+
+### v1.project.branch.created
+
+Fires when a preview branch is created.
+
+```json
+{
+ "branch": {
+ "ref": "abcdefghijklmnoprstu",
+ "name": "feature/login",
+ "git_branch": "feature/login",
+ "is_default": false
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`git_branch` is `null` when the branch is not connected to a Git branch.
+
+### v1.project.branch.updated
+
+Fires when a preview branch is updated.
+
+```json
+{
+ "branch": {
+ "ref": "abcdefghijklmnoprstu",
+ "name": "feature/login",
+ "git_branch": "feature/login",
+ "is_default": false
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`git_branch` is `null` when the branch is not connected to a Git branch.
+
+### v1.project.branch.removed
+
+Fires when a preview branch is deleted.
+
+```json
+{
+ "branch": {
+ "ref": "abcdefghijklmnoprstu",
+ "name": "feature/login",
+ "git_branch": "feature/login",
+ "is_default": false
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`git_branch` is `null` when the branch is not connected to a Git branch.
+
+## Organization events
+
+Organization events fire when something changes at the organization level. The payload always includes `organization_slug` and `project_ref` is always `null`.
+
+| Event | Fires after |
+| --------------------------------------------------------------------------------------- | ----------------------------------------- |
+| [`v1.organization.member.invitation.created`](#v1organizationmemberinvitationcreated) | A member is invited to the organization |
+| [`v1.organization.member.invitation.canceled`](#v1organizationmemberinvitationcanceled) | A pending invitation is canceled |
+| [`v1.organization.member.added`](#v1organizationmemberadded) | A member joins the organization |
+| [`v1.organization.member.removed`](#v1organizationmemberremoved) | A member is removed from the organization |
+| [`v1.organization.member.role.assigned`](#v1organizationmemberroleassigned) | A role is assigned to a member |
+| [`v1.organization.member.role.updated`](#v1organizationmemberroleupdated) | An existing role assignment is updated |
+| [`v1.organization.member.role.removed`](#v1organizationmemberroleremoved) | A role is removed from a member |
+| [`v1.organization.billing.plan.upgraded`](#v1organizationbillingplanupgraded) | The billing plan is upgraded |
+| [`v1.organization.billing.plan.downgraded`](#v1organizationbillingplandowngraded) | The billing plan is downgraded |
+
+### v1.organization.member.invitation.created
+
+Fires when a member is invited to the organization.
+
+```json
+{
+ "member": {
+ "invitation": {
+ "email": "[email protected]",
+ "role": {
+ "name": "Developer",
+ "projects": [{ "ref": "abcdefghijklmnoprstu" }]
+ }
+ }
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`role.projects` is `null` for organization-wide roles that apply to all projects.
+
+### v1.organization.member.invitation.canceled
+
+Fires when a pending invitation is canceled.
+
+```json
+{
+ "member": {
+ "invitation": {
+ "email": "[email protected]"
+ }
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+### v1.organization.member.added
+
+Fires when a member joins the organization by accepting an invitation.
+
+```json
+{
+ "member": {
+ "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
+ "primary_email": "[email protected]",
+ "role": {
+ "name": "Developer",
+ "projects": [{ "ref": "abcdefghijklmnoprstu" }]
+ }
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`role.projects` is `null` for organization-wide roles that apply to all projects.
+
+### v1.organization.member.removed
+
+Fires when a member is removed from the organization.
+
+```json
+{
+ "member": {
+ "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
+ "primary_email": "[email protected]"
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+### v1.organization.member.role.assigned
+
+Fires when a role is assigned to a member.
+
+```json
+{
+ "member": {
+ "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
+ "primary_email": "[email protected]",
+ "role": {
+ "name": "Developer",
+ "projects": [{ "ref": "abcdefghijklmnoprstu" }]
+ }
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`role.projects` is `null` for organization-wide roles that apply to all projects.
+
+### v1.organization.member.role.updated
+
+Fires when an existing role assignment is updated.
+
+```json
+{
+ "member": {
+ "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
+ "primary_email": "[email protected]",
+ "role": {
+ "name": "Admin",
+ "projects": null
+ }
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`role.projects` is `null` for organization-wide roles that apply to all projects.
+
+### v1.organization.member.role.removed
+
+Fires when a role is removed from a member.
+
+```json
+{
+ "member": {
+ "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
+ "primary_email": "[email protected]",
+ "role": {
+ "name": "Developer",
+ "projects": [{ "ref": "abcdefghijklmnoprstu" }]
+ }
+ },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`role.projects` is `null` for organization-wide roles that apply to all projects.
+
+### v1.organization.billing.plan.upgraded
+
+Fires when the organization's billing plan is upgraded.
+
+```json
+{
+ "billing": { "plan": "pro" },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`plan` is one of `free`, `pro`, `team`, or `enterprise`.
+
+### v1.organization.billing.plan.downgraded
+
+Fires when the organization's billing plan is downgraded.
+
+```json
+{
+ "billing": { "plan": "free" },
+ "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
+}
+```
+
+`plan` is one of `free`, `pro`, `team`, or `enterprise`.