平台网络钩子事件

Webhook 事件分为两类范围：

🌐 Webhook events are categorized into two scopes:

• 与特定项目相关的项目事件
• 与组织本身相关的组织活动

想了解平台 Webhooks 的概览，包括传递行为和签名，请参见 Platform Webhooks。

🌐 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
}

组织范围的事件总是将 project_ref 设置为 null，因为它们与特定项目无关。

🌐 Organization scoped events always have project_ref set to null because they do not relate to a specific project.

type 字段中的版本前缀，例如 v1，用于标识有效载荷的架构。关于版本如何随时间变化以及如何处理无法识别的版本，请参见 版本控制。

🌐 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.

出现在所有事件中。当事件是由自动系统进程触发而不是用户触发时，标记为 null。

🌐 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#

仅在通过 发送测试事件 端点发送的测试事件中出现。始终 true。在触发任何副作用之前检查此字段。

🌐 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

当特定项目中发生变化或执行某个操作时，项目事件就会触发。负载总是包括非空的 organization_slug 和 project_ref。

🌐 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 是从零创建的项目的 null。当项目被克隆时，source 承载来源：

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 是以下之一：

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.

使用 source 和 target 来判断从接收组织的角度，转移是外发还是内收。

🌐 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 和 current_status 是以下之一：

actor 是系统发起的过渡的 null。这个事件会在正常的项目操作期间触发，比如重启、升级和扩展。

v1.project.backup.started#

当项目备份开始时触发。

🌐 Fires when a project backup begins.

1
{
2
  "actor": null
3
}

actor 是用于定期备份的 null，在手动触发备份时会带有 user_id。

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 是 null 当分支没有连接到 Git 分支时。

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 是 null 当分支没有连接到 Git 分支时。

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 是 null 当分支没有连接到 Git 分支时。

组织活动 #

🌐 Organization events

当组织级别发生变化时，组织事件就会触发。有效负载总是包含 organization_slug，而 project_ref 总是 null。

🌐 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 是适用于所有项目的全组织角色的 null。

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 是适用于所有项目的全组织角色的 null。

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 是适用于所有项目的全组织角色的 null。

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 是适用于所有项目的全组织角色的 null。

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 是适用于所有项目的全组织角色的 null。

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 是 free、pro、team 或 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 是 free、pro、team 或 enterprise 之一。