Hooks

Important

Helix TeamHub has a new way to add and manage webhooks. The existing Hooks feature is still available in the left navigation pane, but will be deprecated in the future. To add new webhooks that notify external services when new commits are pushed to a repository, use the Webhooks feature instead. To learn more, see Webhooks.

Hooks let you notify external services when:

  • A project has been created, deleted, or updated (company hook)
  • A repository has been created (project hook)
  • A tag/branch has been created or deleted
  • New commits have been pushed to a repository (repository hook)

Helix TeamHub sends an HTTP POST request with a JSON payload to the configured endpoint URL. You can use any endpoint that is capable of processing the request.

A project's or repository's admin can configure project and repository hooks from the Hooks tab.

Adding a hook

To create a hook:

  1. Do one of the following, depending on the type of hook you want to create:

    • For a company hook: Navigate to the Hooks tab in the company scope.

      To make sure you are at the company scope level, click the company name or logo in the top left corner.

    • For a project or repository hook: Navigate to the Hooks tab in the project scope.

      To make sure you are at the correct scope level, click My Dashboard > <project name> for the project scope or click My Dashboard > <project name> > Repositories > <repository name> for the repository scope.

  2. Click the plus icon to open the Add Hook form.
  3. From the service list, select Webhook. All hooks require the same parameters.

  4. Set the parameters as follows:

    • Url: Provide the URL of the endpoint to which the payload is delivered.
    • Content-type: Specify whether the payload is serialized as form (application/x-www-form-urlencoded) (default) or json (application/json).
    • Secret: Optionally, enter a string that is passed with the HTTP requests as an X-Hub-Signature header. The value of this header is computed as the HMAC SHA1 hex digest of the body, using the secret as the key.
    • Insecure ssl: Select if your endpoint is using an SSL certificate that cannot be verified (for example a self-signed certificate).
  5. Optionally, if you want to override the default proxy configuration defined for the Helix TeamHub instance, under Advanced settings, select Use custom proxy configuration; then define a custom URL for the proxy or leave the field empty to disable the proxy altogether.
  6. Click Save hook.

Company hook

Example JSON payload for a new project created webhook:

{
  "operation": "created",
  "type": "project",
  "subject": {
    "id": "chuck",
    "uuid": "a94ea07c-4590-4dc9-b397-c83ca5daf976"
  },
  "project": {
    "id": "test_project",
    "uuid": "c788fd2a-788c-4888-8673-90e027b1b849",
    "name": "Test project",
    "description": "Lorem ipsum",
    "visibility": "company"
  }
}

Project hook

A project webhook lets you notify external services when new repositories are created in Helix TeamHub.

Example JSON payload for a new repository created webhook:

{
  "operation": "created",
  "type": "repository",
  "subject": {
    "id": "chuck",
    "uuid": "a94ea07c-4590-4dc9-b397-c83ca5daf976"
  },
  "project": {
    "id": "test_project",
    "uuid": "c788fd2a-788c-4888-8673-90e027b1b849",
    "name": "Test project"
  },
  "repository": {
    "id": "website",
    "uuid": "ff8f33e9-d619-493e-872d-be7dd4a10235"
    "type": "git"
  }
}

Repository hooks

Repository hooks let you notify external services when new commits are pushed to a repository.

Example JSON payload for a new commit pushed webhook:

{
  "after": "67ec79c2cc2737eec07b649555b3da32c47d095b",
  "ref": "refs/heads/main",
  "before": "c58a421ed77556d217abc7638de9ba9b3589b36d",
  "compare": "",
  "forced": false,
  "created": false,
  "deleted": false,
  "project": {
    "uuid": "c788fd2a-788c-4888-8673-90e027b1b849",
    "name": "Test project",
    "url": "https://helixteamhub.com/example/code/diff/test"
  },
  "repository": {
    "uuid": "ff8f33e9-d619-493e-872d-be7dd4a10235",
    "name": "website",
    "type": "git",
    "url": "https://helixteamhub.com/example/code/overview/test/repositories/website",
    "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/website",
    "ssh_url": "[email protected]:example/projects/test/repositories/git/website",
    "owner": {
      "uuid": "a94ea07c-4590-4dc9-b397-c83ca5daf976",
      "name": "chuck",
      "email": "[email protected]"
    }
  },
  "pusher": {
    "uuid": "a94ea07c-4590-4dc9-b397-c83ca5daf976",
    "name": "chuck",
    "display_name": "Chuck Norris"
  },
  "commit_count": 1,
  "commits": [{
    "distinct": true,
    "removed": [],
    "message": "Update readme",
    "added": [],
    "timestamp": "2015-01-30T12:17:56Z",
    "modified": ["readme"],
    "url": "https://helixteamhub.com/example/code/diff/test/repositories/website/commits/67ec79c2cc2737eec07b649555b3da32c47d095b",
    "author": {
      "name": "Chuck Norris",
      "email": "[email protected]"
    },
    "id": "67ec79c2cc2737eec07b649555b3da32c47d095b"
  }]
}

Example JSON payload for a new branch created webhook:

{
  "after": null,
  "ref": "refs/heads/branch2",
  "before": "",
  "compare": "",
  "forced": false,
  "created": true,
  "deleted": false,
  "project": {
    "uuid": "5a7f9f16-2e2d-4582-b2f6-9cd866fe9b40",
    "name": "Test",
    "url": "https://helixteamhub.com/example/projects/test"
  },
  "repository": {
    "uuid": "02f347d4-5ec2-4189-b5d0-eb487d15cc2e",
    "name": "website",
    "type": "git",
    "url": "https://helixteamhub.com/example/projects/test/repositories/website",
    "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/website",
    "ssh_url": "[email protected]:example/projects/test/repositories/git/website",
    "owner": {
      "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
      "name": "Chuck Norris",
      "email": "[email protected]"
    }
  },
  "pusher": {
    "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
    "name": "Chuck Norris",
    "display_name": "[email protected]"
  },
  "commit_count": 0,
  "commits": []
}

Example JSON payload for a tag deleted webhook:

{
  "after": null,
  "ref": "refs/tags/v3.0",
  "before": "",
  "compare": "",
  "forced": false,
  "created": false,
  "deleted": true,
  "project": {
    "uuid": "5a7f9f16-2e2d-4582-b2f6-9cd866fe9b40",
    "name": "Test",
    "url": "https://helixteamhub.com/example/projects/test"
  },
  "repository": {
    "uuid": "02f347d4-5ec2-4189-b5d0-eb487d15cc2e",
    "name": "website",
    "type": "git",
    "url": "https://helixteamhub.com/example/projects/test/repositories/website",
    "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/website",
    "ssh_url": "[email protected]:example/projects/test/repositories/git/website",
    "owner": {
      "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
      "name": "Chuck Norris",
      "email": "[email protected]"
    },
  },
  "pusher": {
    "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
    "name": "Chuck Norris",
    "display_name": "[email protected]"
  },
  "commit_count": 0,
  "commits": []
}

Code review hooks

Some events are specific to code reviews:

  • code_review - code review created/deleted
  • code_review_title - title updated
  • code_review_description - description updated
  • code_review_threshold - threshold updated
  • code_review_require_build - require build updated
  • code_review_require_task_comments - require task comments updated
  • code_review_state - state updated
  • reviewer - reviewer joined/left/voted/unvoted
  • build - build completed/failed

Example JSON payload a for new code review created webhook:

{
  "operation": "created",
  "type": "code_review",
  "code_review": {
    "uuid": "d9fb853c-cb2e-4f45-962a-b32f2d0f7948",
    "url": "https://helixteamhub.com/example/projects/test/reviews/7",
    "number": 7,
    "state": "open",
    "merge_state": "initial",
    "title": "sdf",
    "description": "",
    "created_at": "2017-11-15T10:35:07Z",
    "updated_at": "2017-11-15T10:35:07Z",
    "deleted_at": null,
    "require_build": false,
    "require_task_comments": false,
    "voting_threshold": 0,
    "base_branch": "test",
    "base_branch_type": "branch",
    "base_commit_id": "dd2b053486ab60ab1d3c4ac6c9b0669f85882894",
    "head_branch": "main",
    "head_branch_type": "branch",
    "head_commit_id": "8e399e9d20df2e6bb74778cfc135510aac65b1de",
    "creator": {
      "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
      "name": "admin",
      "display_name": "Admin"
    },
    "reviewers": [],
    "voters": [],
    "project": {
      "uuid": "372b0f0b-75bf-49c1-b9be-85aa47cdc6e7",
      "name": "test",
      "url": "https://helixteamhub.com/example/projects/test"
    },
    "repository": {
      "uuid": "45b71dd0-3ece-4862-9945-a29acf63cf45",
      "name": "lolo",
      "type": "git",
      "url": "https://helixteamhub.com/example/projects/test/repositories/lolo",
      "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/lolo",
      "ssh_url": "[email protected]:hth/projects/test/repositories/git/lolo",
      "owner": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "email": "[email protected]"
      }
    }
  }
}

Example JSON payload for a new build completed webhook:

{
  "operation": "completed",
  "type": "build",
  "code_reviews": [
    {
      "uuid": "d9fb853c-cb2e-4f45-962a-b32f2d0f7948",
      "url": "https://helixteamhub.com/example/projects/test/reviews/7",
      "number": 7,
      "state": "open",
      "merge_state": "initial",
      "title": "sdf",
      "description": "",
      "created_at": "2017-11-15T10:35:07Z",
      "updated_at": "2017-11-15T10:35:07Z",
      "deleted_at": null,
      "require_build": false,
      "require_task_comments": false,
      "voting_threshold": 0,
      "base_branch": "test",
      "base_branch_type": "branch",
      "base_commit_id": "dd2b053486ab60ab1d3c4ac6c9b0669f85882894",
      "head_branch": "main",
      "head_branch_type": "branch",
      "head_commit_id": "8e399e9d20df2e6bb74778cfc135510aac65b1de",
      "creator": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "display_name": "Admin"
      },
      "reviewers": [],
      "voters": [],
      "project": {
        "uuid": "372b0f0b-75bf-49c1-b9be-85aa47cdc6e7",
        "name": "test",
        "url": "https://helixteamhub.com/example/projects/test"
      },
      "repository": {
        "uuid": "45b71dd0-3ece-4862-9945-a29acf63cf45",
        "name": "lolo",
        "type": "git",
        "url": "https://helixteamhub.com/example/projects/test/repositories/lolo",
        "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/lolo",
        "ssh_url": "[email protected]:hth/projects/test/repositories/git/lolo",
        "owner": {
          "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
          "name": "admin",
          "email": "[email protected]"
        }
      }
    }
  ]
}

Code review comments hooks

A separate group of events is specific to code review comments:

  • code_review_comment - comment created
  • code_review_comment_reply - comment reply created
  • code_review_line_comment - line comment created
  • code_review_line_comment_reply - line comment reply created

Example JSON payload for a new code review comment created webhook:

{
  "operation": "created",
  "type": "code_review_comment",
  "code_review": {
    "uuid": "d9fb853c-cb2e-4f45-962a-b32f2d0f7948",
    "url": "https://helixteamhub.com/example/projects/test/reviews/7",
    "number": 7,
    "state": "open",
    "merge_state": "initial",
    "title": "sdf",
    "description": "",
    "created_at": "2017-11-15T10:35:07Z",
    "updated_at": "2017-11-15T10:35:07Z",
    "deleted_at": null,
    "require_build": false,
    "require_task_comments": false,
    "voting_threshold": 0,
    "base_branch": "test",
    "base_branch_type": "branch",
    "base_commit_id": "dd2b053486ab60ab1d3c4ac6c9b0669f85882894",
    "head_branch": "main",
    "head_branch_type": "branch",
    "head_commit_id": "8e399e9d20df2e6bb74778cfc135510aac65b1de",
    "creator": {
      "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
      "name": "admin",
      "display_name": "Admin"
    },
    "reviewers": [],
    "voters": [],
    "project": {
      "uuid": "372b0f0b-75bf-49c1-b9be-85aa47cdc6e7",
      "name": "test",
      "url": "https://helixteamhub.com/example/projects/test"
    },
    "repository": {
      "uuid": "45b71dd0-3ece-4862-9945-a29acf63cf45",
      "name": "lolo",
      "type": "git",
      "url": "https://helixteamhub.com/example/projects/test/repositories/lolo",
      "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/lolo",
      "ssh_url": "[email protected]:hth/projects/test/repositories/git/lolo",
      "owner": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "email": "[email protected]"
      }
    }
  },
  "comment": {
    "id": "5a0c1e34222b8037f6a37433",
    "type": "code_review",
    "author": {
      "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
      "name": "admin",
      "display_name": "Admin"
    },
    "content": "abc",
    "created_at": "2017-11-15T11:00:04Z",
    "updated_at": "2017-11-15T11:00:04Z",
    "task_comment": false,
    "task_status": null,
    "task_resolved_at": null,
    "task_resolver": null
  }
}

Example JSON payload for a new code review line comment created webhook:

{
  "operation": "created",
  "type": "code_review_line_comment",
  "code_review": {
    "uuid": "d9fb853c-cb2e-4f45-962a-b32f2d0f7948",
    "url": "https://helixteamhub.com/example/projects/test/reviews/7",
    "number": 7,
    "state": "open",
    "merge_state": "initial",
    "title": "sdf",
    "description": "",
    "created_at": "2017-11-15T10:35:07Z",
    "updated_at": "2017-11-15T10:35:07Z",
    "deleted_at": null,
    "require_build": false,
    "require_task_comments": false,
    "voting_threshold": 0,
    "base_branch": "test",
    "base_branch_type": "branch",
    "base_commit_id": "dd2b053486ab60ab1d3c4ac6c9b0669f85882894",
    "head_branch": "main",
    "head_branch_type": "branch",
    "head_commit_id": "8e399e9d20df2e6bb74778cfc135510aac65b1de",
    "creator": {
      "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
      "name": "admin",
      "display_name": "Admin"
    },
    "reviewers": [],
    "voters": [],
    "project": {
      "uuid": "372b0f0b-75bf-49c1-b9be-85aa47cdc6e7",
      "name": "test",
      "url": "https://helixteamhub.com/example/projects/test"
    },
    "repository": {
      "uuid": "45b71dd0-3ece-4862-9945-a29acf63cf45",
      "name": "lolo",
      "type": "git",
      "url": "https://helixteamhub.com/example/projects/test/repositories/lolo",
      "https_url": "https://helixteamhub.com/example/projects/test/repositories/git/lolo",
      "ssh_url": "[email protected]:hth/projects/test/repositories/git/lolo",
      "owner": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "email": "[email protected]"
      }
    }
  },
  "comment": {
    "id": "5a0c1e34222b8037f6a37433",
    "type": "code_review",
    "author": {
      "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
      "name": "admin",
      "display_name": "Admin"
    },
    "content": "abc",
    "created_at": "2017-11-15T11:00:04Z",
    "updated_at": "2017-11-15T11:00:04Z",
    "line_number": 1,
    "computed_line_number": 1,
    "line_type": "added",
    "outdated": false,
    "diff_handle": [
      { "type": "range", "content": "@@ -0,0 +1,1 @@", "old_start_line": 0, "new_start_line": 1 },
      { "content": "+d213sf", "type": "added" }
    ],
    "task_comment": false,
    "task_status": null,
    "task_resolved_at": null,
    "task_resolver": null
  }
}