General

Webhooks let you notify external services when:

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 webhook

To create a webhook:

  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.
    • For a project or repository hook: Navigate to the Hooks tab in the project 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/master",
  "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": "hth@helixteamhub.com:example/projects/test/repositories/git/website",
    "owner": {
      "uuid": "a94ea07c-4590-4dc9-b397-c83ca5daf976",
      "name": "chuck",
      "email": "chuck@example.com"
    }
  },
  "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": "chuck@example.com"
    },
    "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": "hth@helixteamhub.com:example/projects/test/repositories/git/website",
    "owner": {
      "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
      "name": "Chuck Norris",
      "email": "chuck@example.com"
    }
  },
  "pusher": {
    "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
    "name": "Chuck Norris",
    "display_name": "chuck@example.com"
  },
  "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": "hth@helixteamhub.com:example/projects/test/repositories/git/website",
    "owner": {
      "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
      "name": "Chuck Norris",
      "email": "chuck@example.com"
    },
  },
  "pusher": {
    "uuid": "bb501310-0292-4925-88e3-ba3b3d53a795",
    "name": "Chuck Norris",
    "display_name": "chuck@example.com"
  },
  "commit_count": 0,
  "commits": []
}

Code review hooks

Some events are specific to code reviews:

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": "master",
    "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": "hth@helixteamhub.com:hth/projects/test/repositories/git/lolo",
      "owner": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "email": "chuck@example.com"
      }
    }
  }
}

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": "master",
      "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": "hth@helixteamhub.com:hth/projects/test/repositories/git/lolo",
        "owner": {
          "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
          "name": "admin",
          "email": "chuck@example.com"
        }
      }
    }
  ]
}

Code review comments hooks

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

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": "master",
    "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": "hth@helixteamhub.com:hth/projects/test/repositories/git/lolo",
      "owner": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "email": "chuck@example.com"
      }
    }
  },
  "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": "master",
    "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": "hth@helixteamhub.com:hth/projects/test/repositories/git/lolo",
      "owner": {
        "uuid": "9db5061d-42a9-4a1b-8115-0f673c24516f",
        "name": "admin",
        "email": "chuck@example.com"
      }
    }
  },
  "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
  }
}
Updated on: 19 December 2017