> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps Webhook Setup Guide

> Configure Azure DevOps to deliver events to StackOne.

## Prerequisites

Before continuing, you should have already completed the following for this connector:

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/guides/explore-connectors">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/azuredevops/guides/connector-profile/oauth-2-0-microsoft-entra-id" icon="https://stackone-logos.com/api/azure-devops/filled/png" horizontal>
        Azure DevOps - OAuth 2.0 (Microsoft Entra ID)
      </Card>

      <Card title="Connector Profile" href="/connectors/azuredevops/guides/connector-profile/personal-access-token" icon="https://stackone-logos.com/api/azure-devops/filled/png" horizontal>
        Azure DevOps - Personal Access Token
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/guides/embedding-stackone-hub">StackOne Hub</a> or <a href="/guides/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/azuredevops/guides/link-account/oauth-2-0-microsoft-entra-id" icon="https://stackone-logos.com/api/azure-devops/filled/png" horizontal>
        Azure DevOps - OAuth 2.0 (Microsoft Entra ID)
      </Card>

      <Card title="Link Account" href="/connectors/azuredevops/guides/link-account/personal-access-token" icon="https://stackone-logos.com/api/azure-devops/filled/png" horizontal>
        Azure DevOps - Personal Access Token
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Subscribe via the StackOne dashboard</h2>

  <p>This connector uses <strong>Programmatic Webhooks</strong>. When you enable webhook events for a connected Azure DevOps account, StackOne automatically creates one Service Hook subscription per enabled event (via `POST /_apis/hooks/subscriptions?api-version=7.1`), each pointing at your StackOne callback URL. Azure DevOps requires a separate subscription per event type — StackOne manages their full lifecycle.</p>

  <Steps>
    <Step title="Ensure the required scope or PAT permission">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Before enabling webhook events, confirm your connected account has the necessary permissions.</p>

        <ul>
          <li><strong>OAuth 2.0 (Microsoft Entra ID):</strong> Ensure the `vso.hooks_write` scope is included in your app registration's granted permissions.</li>
          <li><strong>Personal Access Token:</strong> Generate the PAT with <strong>Service Hooks (Read & write)</strong> permission (under <strong>Organization</strong> scopes in the PAT creation dialog).</li>
        </ul>
      </div>
    </Step>

    <Step title="Select event subscriptions in the dashboard">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the StackOne dashboard, open the Azure DevOps connector profile and enable the webhook events you want delivered downstream. See the <strong>Available Webhook Events</strong> section below for the full list.</p>
      </div>
    </Step>

    <Step title="Project scoping and the Project name field">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Set the <strong>Project name (webhook scoping)</strong> config field to your project's name — the `{project}` segment of your project URL, `https://dev.azure.com/{organization}/{project}` (e.g. `my-project`). StackOne resolves that name to the internal project ID automatically, so you never need to look up a GUID. The field is optional, but whether you must set it depends on which events you enable:</p>

        <ul>
          <li><strong>Organization-level or project-level</strong> — work item, git, pull request, and build events. Leave Project name blank to receive them from every project in the organization, or set it to scope them to a single project.</li>
          <li><strong>Project-level only (Project name required)</strong> — pipeline events (run / stage / job state changed). Azure DevOps rejects these if created at the organization level, so their subscriptions fail unless Project name is set.</li>
        </ul>
      </div>
    </Step>

    <Step title="Registration on subscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>When webhook events are enabled (or the event selection changes), StackOne creates the corresponding Service Hook subscriptions on your behalf. You can inspect them in Azure DevOps under <strong>Organization Settings > Service hooks</strong> (or <strong>Project Settings > Service hooks</strong> for project-scoped subscriptions).</p>
      </div>
    </Step>

    <Step title="Verify delivery">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Trigger a matching change in Azure DevOps (for example, create a work item) and confirm the event reaches your downstream consumer.</p>

        <ul>
          <li>Azure DevOps posts each event as a JSON payload; StackOne responds with `200 OK` automatically.</li>
          <li>Delivery history and retries are visible in Azure DevOps under <strong>Service hooks > History</strong> for each subscription.</li>
        </ul>
      </div>
    </Step>

    <Step title="Unsubscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Changing your event selection creates subscriptions for newly enabled events and deletes the ones for disabled events. Disconnecting the account deletes all StackOne-managed subscriptions, stopping deliveries.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available Webhook Events</h2>

  <p>The following Azure DevOps events can be enabled. Each enabled event is registered as its own Service Hook subscription.</p>

  <Steps>
    <Step title="Work Item events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on work items (bugs, tasks, user stories, etc.) across all work item types.</p>

        <ul>
          <li><strong>Work Item Created</strong> (`workitem.created`) — Fired when a new work item is created</li>
          <li><strong>Work Item Updated</strong> (`workitem.updated`) — Fired when a work item's fields are changed</li>
          <li><strong>Work Item Deleted</strong> (`workitem.deleted`) — Fired when a work item is permanently deleted</li>
          <li><strong>Work Item Restored</strong> (`workitem.restored`) — Fired when a deleted work item is restored</li>
          <li><strong>Work Item Commented</strong> (`workitem.commented`) — Fired when a comment is added to a work item</li>
        </ul>
      </div>
    </Step>

    <Step title="Git and Pull Request events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on Git repositories, pushes, and pull requests.</p>

        <ul>
          <li><strong>Git Push</strong> (`git.push`) — Fired when commits are pushed to a repository</li>
          <li><strong>Pull Request Created</strong> (`git.pullrequest.created`) — Fired when a new pull request is opened</li>
          <li><strong>Pull Request Updated</strong> (`git.pullrequest.updated`) — Fired when a pull request is updated</li>
          <li><strong>Pull Request Merged</strong> (`git.pullrequest.merged`) — Fired when a pull request is completed (merged)</li>
          <li><strong>Pull Request Comment</strong> (`ms.vss-code.git-pullrequest-comment-event`) — Fired when a comment is added to a pull request</li>
        </ul>
      </div>
    </Step>

    <Step title="Build events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on classic and YAML pipeline builds.</p>

        <ul>
          <li><strong>Build Complete</strong> (`build.complete`) — Fired when a build finishes (any result: succeeded, failed, partially succeeded, canceled)</li>
        </ul>
      </div>
    </Step>

    <Step title="Pipeline events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on Azure Pipelines runs, stages, and jobs. These events use publisher `pipelines`.</p>

        <ul>
          <li><strong>Pipeline Run State Changed</strong> (`ms.vss-pipelines.run-state-changed-event`) — Fired when a pipeline run changes state</li>
          <li><strong>Pipeline Stage State Changed</strong> (`ms.vss-pipelines.stage-state-changed-event`) — Fired when a stage within a run changes state</li>
          <li><strong>Pipeline Job State Changed</strong> (`ms.vss-pipelines.job-state-changed-event`) — Fired when a job within a stage changes state</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Azure DevOps delivers events to StackOne.</p>

  <Steps>
    <Step title="JSON payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Azure DevOps delivers each event as an HTTP POST with a JSON body. The common envelope contains `id` (a GUID used as the event ID), `eventType` (e.g. `workitem.created`), `publisherId`, `createdDate`, and `resource` (the event-specific data).</p>
      </div>
    </Step>

    <Step title="No signature verification">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Azure DevOps Service Hooks do not include HMAC signature headers. Deliveries are authenticated solely by the fact that the callback URL is known only to StackOne and Azure DevOps.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.