FAfactorialhr
Webhooks

Teams > Team > Moves

Subscription_type: teams/team/move. Triggered when a team is moved under a different parent team (or to the root of the hierarchy), whether the move is made through the API or from Factorial. This event belongs to the 2026-10-01 contract, where the payload carries the public team fields plus the resulting position — parent_team_id is the new parent (null when moved to the root) and depth its new level. A subscription pinned to an earlier version still receives the event, but without those two fields, and the hierarchy is absent from the teams read on those versions too, so upgrading is the only way to obtain the new position rather than infer it. The memberships re-propagated to the new ancestors are created afterwards and emit no membership events of their own, so a subscriber tracking who belongs where has to read the affected sub-tree.

postWebhookWebhooks > Teams > Team > Moves

Payload

idstring required

Unique identifier of the team

namestring required

Human-readable name of the team (e.g. "Engineering")

descriptionstring

Free-text description of the team

avatarstring

URL of the team's avatar image (null when the team has none)

employee_idsstring[]

IDs of the employees who are members of this team

lead_idsstring[]

IDs of the employees who are leads of this team (subset of employee_ids)

company_idstring required

ID of the company this team belongs to

depthinteger

Depth of this team in the nested-team hierarchy: 1 for a top-level team, 2 for its children, and so on. Returned by read, create and move; null on update and delete, which do not change the hierarchy, and always null for companies without nested teams.

parent_team_idstring

ID of the parent team this team is nested under (null for a root team). Returned by read, create and move; null on update and delete, which do not change the hierarchy, and always null for companies without nested teams.

Example payload

{
  "id": "1",
  "name": "Engineering",
  "description": "Engineering team description",
  "avatar": "https://api.factorialhr.com/rails/active_storage/representations/redirect/team.png",
  "employee_ids": [
    "10",
    "12"
  ],
  "lead_ids": [
    "10"
  ],
  "company_id": "1",
  "depth": 2,
  "parent_team_id": "5"
}

Response

Return a 200 status to indicate that the data was received successfully

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.