Platform Webhook Events

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.

Event envelope

Every event arrives in the same envelope regardless of type:

{
  "id": "<event UUID>",
  "type": "<event-type>",
  "timestamp": "<ISO 8601 UTC>",
  "payload": {
    "organization_slug": "<org-slug>",
    "project_ref": "<project-ref>"
    // event-specific fields
  }
}

For example:

{
  "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.

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.

"actor": {
  "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e"
}

is_test

Present only on test events sent through the 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.

v1.project.created

Fires when a project is created and begins initial setup. When receiving this event, a project might not be healthy yet.

{
  "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:

"source": {
  "type": "clone",
  "project_ref": "abcdefghijklmnoprstu"
}

v1.project.paused

Fires when a project is paused.

{
  "reason": "inactivity",
  "actor": null
}

reason is one of the following:

v1.project.restored

Fires when a paused project is restored. When receiving this event, a project might not be healthy yet.

{
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
}

v1.project.restarted

Fires when a project is restarted.

{
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
}

v1.project.removed

Fires when a project is deleted.

{
  "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.

{
  "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.

{
  "previous_status": "RESTARTING",
  "current_status": "ACTIVE_HEALTHY",
  "actor": null
}

previous_status and current_status are one of:

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

v1.organization.member.invitation.created

Fires when a member is invited to the organization.

{
  "member": {
    "invitation": {
      "email": "user@example.com",
      "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.

{
  "member": {
    "invitation": {
      "email": "user@example.com"
    }
  },
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
}

v1.organization.member.added

Fires when a member joins the organization by accepting an invitation.

{
  "member": {
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
    "primary_email": "user@example.com",
    "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.

{
  "member": {
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
    "primary_email": "user@example.com"
  },
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
}

v1.organization.member.role.assigned

Fires when a role is assigned to a member.

{
  "member": {
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
    "primary_email": "user@example.com",
    "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.

{
  "member": {
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
    "primary_email": "user@example.com",
    "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.

{
  "member": {
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
    "primary_email": "user@example.com",
    "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.

{
  "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.

{
  "billing": { "plan": "free" },
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
}

plan is one of free, pro, team, or enterprise.