> ## 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 Blob Storage Webhook Setup Guide

> Configure Azure Blob Storage 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/azureblobstorage/guides/connector-profile/oauth-2-0-entra-id" icon="https://stackone-logos.com/api/microsoft-azure/filled/png" horizontal>
        Azure Blob Storage - OAuth 2.0 (Entra ID)
      </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/azureblobstorage/guides/link-account/oauth-2-0-entra-id" icon="https://stackone-logos.com/api/microsoft-azure/filled/png" horizontal>
        Azure Blob Storage - OAuth 2.0 (Entra ID)
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Subscribe via the Azure portal</h2>

  <p>This connector uses <strong>Manual Webhooks</strong>. You must create an Azure Event Grid subscription yourself in the Azure portal, pointing at the StackOne webhook URL shown on this connection.</p>

  <Steps>
    <Step title="Register the Microsoft.EventGrid resource provider (one-time)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Event Grid can only create system topics and subscriptions once the <strong>Microsoft.EventGrid</strong> resource provider is registered on the Azure subscription. This is a one-time setup per Azure subscription — skip it only if Event Grid is already in use there. If it is not registered, creating the subscription fails with *"The subscription is not registered to use namespace 'Microsoft.EventGrid'"*.</p>

        <ul>
          <li>In the <a href="https://portal.azure.com" target="_blank" rel="noopener noreferrer">Azure portal</a>, search for and open <strong>Subscriptions</strong>, then select the subscription that contains your storage account.</li>
          <li>In the left menu, go to <strong>Settings > Resource providers</strong>.</li>
          <li>Search for <strong>Microsoft.EventGrid</strong>, select it, and click <strong>Register</strong> (wait until Status shows <strong>Registered</strong>, \~1–2 minutes).</li>
          <li>Alternatively via Azure CLI: `az provider register --namespace Microsoft.EventGrid`</li>
          <li>Registering a resource provider requires <strong>Contributor</strong> or <strong>Owner</strong> on the Azure subscription — a subscription admin may need to do this step.</li>
        </ul>
      </div>
    </Step>

    <Step title="Copy the Native Webhook URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Before configuring the Event Grid subscription, copy the <strong>Native Webhook URL</strong> from this connection.</p>

        <ul>
          <li>The URL is shown in the <strong>Native Webhook URL</strong> field on the connection settings page — it is only available after the connection has been created.</li>
          <li>Copy the full URL and keep it ready for the next step.</li>
        </ul>
      </div>
    </Step>

    <Step title="Create or confirm an Event Grid system topic on your storage account">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Open the <a href="https://portal.azure.com" target="_blank" rel="noopener noreferrer">Azure portal</a> and navigate to your storage account.</p>

        <ul>
          <li>In the left sidebar, click <strong>Events</strong>.</li>
          <li>If no system topic exists yet, Azure creates one automatically when you add the first subscription.</li>
          <li>Note: your storage account must be in a region that supports Event Grid (most regions do).</li>
        </ul>
      </div>
    </Step>

    <Step title="Create a new Event Grid subscription">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the <strong>Events</strong> blade of your storage account, click <strong>+ Event Subscription</strong>.</p>

        <ul>
          <li><strong>Name</strong>: Enter a descriptive name (e.g., `stackone-webhook`).</li>
          <li><strong>Event Schema</strong>: Leave as <strong>Event Grid Schema</strong>.</li>
          <li><strong>Filter to Event Types</strong>: Select the event types you want to receive (e.g., Blob Created, Blob Deleted). You can select multiple.</li>
          <li><strong>Endpoint Type</strong>: Select <strong>Web Hook</strong>.</li>
          <li><strong>Endpoint</strong>: Paste the Native Webhook URL you copied in step 1.</li>
          <li><strong>Additional Features</strong>: Leave <strong>Max events per batch</strong> at its default (1). Batched delivery is not supported — only the first event in a batched request is processed.</li>
          <li>Click <strong>Create</strong>.</li>
        </ul>
      </div>
    </Step>

    <Step title="SubscriptionValidation handshake">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Azure Event Grid immediately sends a validation request to the endpoint when the subscription is created.</p>

        <ul>
          <li>StackOne automatically responds to the handshake with the required `validationResponse` — no action is needed from you.</li>
          <li>If creation reports endpoint validation failure, verify the Native Webhook URL is correct and the connection is active.</li>
        </ul>
      </div>
    </Step>

    <Step title="Verify delivery">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Trigger a blob operation (upload or delete a file) in the storage account and confirm the event reaches your downstream consumer.</p>

        <ul>
          <li>Azure Event Grid retries failed deliveries with exponential backoff for up to 24 hours by default.</li>
          <li>Delivery status is visible in the Azure portal under the Event Grid subscription's <strong>Metrics</strong> and <strong>Dead-letter</strong> blades.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>The following Azure Blob Storage events can be received. Subscribe to the corresponding event types when creating the Event Grid subscription.</p>

  <Steps>
    <Step title="Standard blob events (all storage accounts)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>These events are available on all Azure Blob Storage accounts.</p>

        <ul>
          <li><strong>Blob Created</strong> (`Microsoft.Storage.BlobCreated`) — Fired when a blob is successfully created or replaced (PutBlob, CopyBlob, PutBlockList, FlushWithClose)</li>
          <li><strong>Blob Deleted</strong> (`Microsoft.Storage.BlobDeleted`) — Fired when a blob is deleted (DeleteBlob, DeleteFile)</li>
          <li><strong>Blob Tier Changed</strong> (`Microsoft.Storage.BlobTierChanged`) — Fired when a block blob's access tier changes (SetBlobTier)</li>
          <li><strong>Async Operation Initiated</strong> (`Microsoft.Storage.AsyncOperationInitiated`) — Fired when a blob operation is initiated and its data is still being retrieved (e.g. archive rehydration start)</li>
        </ul>
      </div>
    </Step>

    <Step title="Data Lake Storage Gen2 events (HNS-enabled accounts only)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>These events are only available on storage accounts with hierarchical namespace enabled (Azure Data Lake Storage Gen2).</p>

        <ul>
          <li><strong>Blob Renamed</strong> (`Microsoft.Storage.BlobRenamed`) — Fired when a blob is renamed (RenameFile)</li>
          <li><strong>Directory Created</strong> (`Microsoft.Storage.DirectoryCreated`) — Fired when a directory is created (CreateDirectory)</li>
          <li><strong>Directory Renamed</strong> (`Microsoft.Storage.DirectoryRenamed`) — Fired when a directory is renamed (RenameDirectory)</li>
          <li><strong>Directory Deleted</strong> (`Microsoft.Storage.DirectoryDeleted`) — Fired when a directory is deleted (DeleteDirectory)</li>
        </ul>
      </div>
    </Step>

    <Step title="Policy events (scheduled)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>These events fire when an account-scheduled policy run completes. They run on Azure's daily schedule and cannot be triggered on demand.</p>

        <ul>
          <li><strong>Blob Inventory Policy Completed</strong> (`Microsoft.Storage.BlobInventoryPolicyCompleted`) — Fired when a blob inventory policy run completes</li>
          <li><strong>Lifecycle Policy Completed</strong> (`Microsoft.Storage.LifecyclePolicyCompleted`) — Fired when a lifecycle management policy run completes</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

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

  <Steps>
    <Step title="JSON array envelope">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Azure Event Grid delivers events as an HTTP POST with a JSON array body. Each array element is an event envelope with fields id (GUID), eventType, subject, eventTime, topic, dataVersion, metadataVersion, and data (the blob-specific payload). Event Grid delivers one event per request by default — do not enable batched delivery (Max events per batch must remain 1), as only the first event in each request is processed.</p>
      </div>
    </Step>

    <Step title="No signature verification">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Azure Event Grid (Event Grid Schema) does not include HMAC signature headers. Deliveries are authenticated solely by endpoint URL secrecy.</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.