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:

1
{
2
  "id": "<event UUID>",
3
  "type": "<event-type>",
4
  "timestamp": "<ISO 8601 UTC>",
5
  "payload": {
6
    "organization_slug": "<org-slug>",
7
    "project_ref": "<project-ref>"
8
    // event-specific fields
9
  }
10
}

For example:

1
{
2
  "id": "019f3c9c-c758-766d-acb2-94eb089b3f69",
3
  "type": "v1.project.paused",
4
  "timestamp": "2026-07-07T12:45:35.449Z",
5
  "payload": {
6
    "project_ref": "your-project-ref",
7
    "organization_slug": "your-org-slug",
8
    "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
9
  }
10
}

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.

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

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.

1
{
2
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" },
3
  "source": null
4
}

source is null for projects created from scratch. When a project is cloned, source carries the origin:

1
"source": {
2
  "type": "clone",
3
  "project_ref": "abcdefghijklmnoprstu"
4
}

v1.project.paused#

Fires when a project is paused.

1
{
2
  "reason": "inactivity",
3
  "actor": null
4
}

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.

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

v1.project.restarted#

Fires when a project is restarted.

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

v1.project.removed#

Fires when a project is deleted.

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

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.

1
{
2
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" },
3
  "source": { "organization_slug": "from-org" },
4
  "target": { "organization_slug": "to-org" }
5
}

v1.project.status.changed#

Fires when a project's status transitions.

1
{
2
  "previous_status": "RESTARTING",
3
  "current_status": "ACTIVE_HEALTHY",
4
  "actor": null
5
}

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.

1
{
2
  "actor": null
3
}

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.

1
{
2
  "branch": {
3
    "ref": "abcdefghijklmnoprstu",
4
    "name": "feature/login",
5
    "git_branch": "feature/login",
6
    "is_default": false
7
  },
8
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
9
}

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.

1
{
2
  "branch": {
3
    "ref": "abcdefghijklmnoprstu",
4
    "name": "feature/login",
5
    "git_branch": "feature/login",
6
    "is_default": false
7
  },
8
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
9
}

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.

1
{
2
  "branch": {
3
    "ref": "abcdefghijklmnoprstu",
4
    "name": "feature/login",
5
    "git_branch": "feature/login",
6
    "is_default": false
7
  },
8
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
9
}

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.

1
{
2
  "member": {
3
    "invitation": {
4
      "email": "user@example.com",
5
      "role": {
6
        "name": "Developer",
7
        "projects": [{ "ref": "abcdefghijklmnoprstu" }]
8
      }
9
    }
10
  },
11
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
12
}

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.

1
{
2
  "member": {
3
    "invitation": {
4
      "email": "user@example.com"
5
    }
6
  },
7
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
8
}

v1.organization.member.added#

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

1
{
2
  "member": {
3
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
4
    "primary_email": "user@example.com",
5
    "role": {
6
      "name": "Developer",
7
      "projects": [{ "ref": "abcdefghijklmnoprstu" }]
8
    }
9
  },
10
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
11
}

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.

1
{
2
  "member": {
3
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
4
    "primary_email": "user@example.com"
5
  },
6
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
7
}

v1.organization.member.role.assigned#

Fires when a role is assigned to a member.

1
{
2
  "member": {
3
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
4
    "primary_email": "user@example.com",
5
    "role": {
6
      "name": "Developer",
7
      "projects": [{ "ref": "abcdefghijklmnoprstu" }]
8
    }
9
  },
10
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
11
}

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.

1
{
2
  "member": {
3
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
4
    "primary_email": "user@example.com",
5
    "role": {
6
      "name": "Admin",
7
      "projects": null
8
    }
9
  },
10
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
11
}

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.

1
{
2
  "member": {
3
    "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e",
4
    "primary_email": "user@example.com",
5
    "role": {
6
      "name": "Developer",
7
      "projects": [{ "ref": "abcdefghijklmnoprstu" }]
8
    }
9
  },
10
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
11
}

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.

1
{
2
  "billing": { "plan": "pro" },
3
  "actor": { "user_id": "6cf38595-f5ff-43ca-ba0f-84617bbe192e" }
4
}

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

v1.organization.billing.plan.downgraded#

Fires when the organization's billing plan is downgraded.

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

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