Azure Event Grid
Complete Guide

[
  {
    "id": "b4a8e5e2-1234-4c3f-a9b0-12345abc6789",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/myaccount",
    "subject": "/blobServices/default/containers/uploads/blobs/report.pdf",
    "eventType": "Microsoft.Storage.BlobCreated",
    "eventTime": "2026-05-04T10:30:00.000Z",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "data": {
      "api": "PutBlob",
      "clientRequestId": "abc123",
      "requestId": "def456",
      "eTag": "0x8D4BCC2E4835CD0",
      "contentType": "application/pdf",
      "contentLength": 524288,
      "blobType": "BlockBlob",
      "url": "https://myaccount.blob.core.windows.net/uploads/report.pdf",
      "sequencer": "00000000000004420000000000028963"
    }
  }
]

{
  "specversion": "1.0",
  "type": "Microsoft.Storage.BlobCreated",
  "source": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/myaccount",
  "id": "b4a8e5e2-1234-4c3f-a9b0-12345abc6789",
  "time": "2026-05-04T10:30:00.000Z",
  "subject": "/blobServices/default/containers/uploads/blobs/report.pdf",
  "datacontenttype": "application/json",
  "data": {
    "api": "PutBlob",
    "url": "https://myaccount.blob.core.windows.net/uploads/report.pdf",
    "contentType": "application/pdf",
    "contentLength": 524288,
    "blobType": "BlockBlob"
  }
}

# Create a system topic for a Storage Account
az eventgrid system-topic create \
  --resource-group myRG \
  --name myStorageSystemTopic \
  --location eastus \
  --topic-type Microsoft.Storage.StorageAccounts \
  --source /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.Storage/storageAccounts/mystorageaccount

# Create a custom topic
az eventgrid topic create \
  --resource-group myRG \
  --name order-events \
  --location eastus \
  --input-schema cloudeventschemav1_0 \
  --public-network-access enabled

# Create subscription pointing to an Azure Function
az eventgrid event-subscription create \
  --name blob-created-sub \
  --source-resource-id /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.Storage/storageAccounts/mystorageaccount \
  --endpoint-type azurefunction \
  --endpoint /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.Web/sites/myFunctionApp/functions/ProcessBlob \
  --included-event-types Microsoft.Storage.BlobCreated \
  --subject-begins-with /blobServices/default/containers/uploads/ \
  --deadletter-endpoint /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.Storage/storageAccounts/mydeadletter/blobServices/default/containers/deadletter

resource eventSubscription 'Microsoft.EventGrid/eventSubscriptions@2022-06-15' = {
  name: 'order-created-subscription'
  scope: customTopic
  properties: {
    destination: {
      endpointType: 'ServiceBusTopic'
      properties: {
        resourceId: serviceBusTopic.id
      }
    }
    filter: {
      includedEventTypes: [ 'Orders.Created', 'Orders.Updated' ]
      subjectBeginsWith: '/orders/'
      advancedFilters: [
        {
          operatorType: 'NumberGreaterThan'
          key: 'data.amount'
          value: 100
        }
      ]
    }
    deadLetterDestination: {
      endpointType: 'StorageBlob'
      properties: {
        resourceId: storageAccount.id
        blobContainerName: 'deadletter'
      }
    }
    retryPolicy: {
      maxDeliveryAttempts: 30
      eventTimeToLiveInMinutes: 1440
    }
    eventDeliverySchema: 'CloudEventSchemaV1_0'
  }
}

{
  "filter": {
    "includedEventTypes": ["Orders.Created"],
    "subjectBeginsWith": "/orders/",
    "advancedFilters": [
      {
        "operatorType": "StringIn",
        "key": "data.region",
        "values": ["EU-West", "EU-North"]
      },
      {
        "operatorType": "NumberGreaterThanOrEquals",
        "key": "data.amount",
        "value": 500
      },
      {
        "operatorType": "BoolEquals",
        "key": "data.isPriority",
        "value": true
      },
      {
        "operatorType": "StringNotContains",
        "key": "data.status",
        "values": ["cancelled", "refunded"]
      }
    ]
  }
}

# Add dead-letter storage to an existing subscription
az eventgrid event-subscription update \
  --name my-subscription \
  --source-resource-id <topic-resource-id> \
  --deadletter-endpoint \
    /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.Storage/storageAccounts/mydeadletter/blobServices/default/containers/dead-events

# Dead-letter blob path format:
# <container>/<topic-name>/<subscription-name>/<year>/<month>/<day>/<hour>/<eventId>.json

using Azure.Messaging.EventGrid.Namespaces;

var client = new EventGridReceiverClient(
    new Uri("https://<namespace>.eastus-1.eventgrid.azure.net"),
    "<topic-name>",
    "<subscription-name>",
    new DefaultAzureCredential());

// Receive a batch of events (with lock — must acknowledge within lock duration)
ReceiveResult result = await client.ReceiveAsync(maxEvents: 10, maxWaitTime: TimeSpan.FromSeconds(30));

var lockTokens = new List<string>();
foreach (ReceiveDetails detail in result.Value)
{
    CloudEvent cloudEvent = detail.Event;
    BrokerProperties broker = detail.BrokerProperties;

    Console.WriteLine($"Event: {cloudEvent.Type}, LockToken: {broker.LockToken}");

    // Process the event...
    bool success = await ProcessEventAsync(cloudEvent);

    if (success)
        lockTokens.Add(broker.LockToken); // Acknowledge
    else
        await client.ReleaseAsync(new[] { broker.LockToken }); // Return to queue
}

// Acknowledge successfully processed events
if (lockTokens.Any())
    await client.AcknowledgeAsync(lockTokens);

// ASP.NET Core webhook handler with validation
[HttpPost("webhook")]
public async Task<IActionResult> ReceiveEvent()
{
    string requestContent = await new StreamReader(Request.Body).ReadToEndAsync();

    // CloudEvents uses HTTP OPTIONS for handshake — different from Event Grid schema
    if (Request.Headers["WebHook-Request-Origin"].Count > 0)
    {
        // CloudEvents webhook validation
        Response.Headers["WebHook-Allowed-Origin"] = Request.Headers["WebHook-Request-Origin"].ToString();
        return Ok();
    }

    // Event Grid schema validation
    var events = JsonSerializer.Deserialize<JsonElement[]>(requestContent);
    foreach (var evt in events!)
    {
        if (evt.GetProperty("eventType").GetString() == "Microsoft.EventGrid.SubscriptionValidationEvent")
        {
            var validationCode = evt.GetProperty("data")
                                    .GetProperty("validationCode").GetString();
            return Ok(new { validationResponse = validationCode });
        }

        // Process real events
        await HandleEventAsync(evt);
    }
    return Ok();
}

# Create private endpoint so publishers inside VNet can publish securely
az network private-endpoint create \
  --name egrid-publish-pe \
  --resource-group myRG \
  --vnet-name myVNet \
  --subnet mySubnet \
  --private-connection-resource-id \
    /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.EventGrid/topics/order-events \
  --group-ids topic \
  --connection-name egrid-private-conn

# Private DNS zone for Event Grid
az network private-dns zone create \
  --resource-group myRG \
  --name "privatelink.eventgrid.azure.net"

{
  "triggers": {
    "When_a_resource_event_occurs": {
      "type": "ApiConnectionWebhook",
      "inputs": {
        "host": {
          "connection": {
            "name": "@parameters('$connections')['azureeventgrid']['connectionId']"
          }
        },
        "path": "/subscriptions/@{encodeURIComponent('<sub-id>')}/providers/@{encodeURIComponent('Microsoft.KeyVault.vaults')}/resource/eventSubscriptions",
        "body": {
          "properties": {
            "destination": {
              "endpointType": "webhook",
              "properties": { "endpointUrl": "@{listCallbackUrl()}" }
            },
            "filter": {
              "includedEventTypes": [
                "Microsoft.KeyVault.SecretNearExpiry",
                "Microsoft.KeyVault.SecretExpired"
              ]
            }
          }
        }
      }
    }
  },
  "actions": {
    "Send_Teams_Alert": {
      "type": "Http",
      "inputs": {
        "method": "POST",
        "uri": "@parameters('teamsWebhookUrl')",
        "body": {
          "text": "🔑 Key Vault Alert: @{triggerBody()?['subject']} — @{triggerBody()?['eventType']}"
        }
      }
    }
  }
}

using Azure.Messaging.EventGrid;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

public class BlobEventProcessor
{
    private readonly ILogger<BlobEventProcessor> _logger;

    public BlobEventProcessor(ILogger<BlobEventProcessor> logger) => _logger = logger;

    [Function("ProcessBlobEvent")]
    public async Task Run(
        [EventGridTrigger] EventGridEvent eventGridEvent)
    {
        _logger.LogInformation("Event: {Type}, Subject: {Subject}",
            eventGridEvent.EventType, eventGridEvent.Subject);

        if (eventGridEvent.EventType == "Microsoft.Storage.BlobCreated")
        {
            var data = eventGridEvent.Data!.ToObjectFromJson<BlobCreatedData>();
            _logger.LogInformation("Blob URL: {Url}, Size: {Size}", data.Url, data.ContentLength);
            await ProcessNewBlobAsync(data.Url);
        }
    }
}

// CloudEvents trigger
public class OrderEventProcessor
{
    [Function("ProcessOrderEvent")]
    public async Task Run(
        [EventGridTrigger] CloudEvent cloudEvent,
        ILogger log)
    {
        log.LogInformation("CloudEvent type: {Type}", cloudEvent.Type);

        var order = cloudEvent.Data!.ToObjectFromJson<OrderCreatedData>();
        await RouteOrderAsync(order);
    }
}

public record BlobCreatedData(string Url, string ContentType, long ContentLength, string BlobType);
public record OrderCreatedData(string OrderId, decimal Amount, string Region, bool IsPriority);

[Function("CreateOrder")]
[EventGridOutput(TopicEndpointUri = "ORDER_EVENTS_ENDPOINT", TopicKeySetting = "ORDER_EVENTS_KEY")]
public static EventGridEvent Run(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
{
    var order = JsonSerializer.Deserialize<Order>(req.Body);
    return new EventGridEvent(
        subject: $"/orders/{order.OrderId}",
        eventType: "Orders.Created",
        dataVersion: "1.0",
        data: order);
}

// CloudEvents output binding
[Function("CreateOrderCloudEvent")]
public async Task<CloudEvent> Run(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req)
{
    var order = await req.ReadFromJsonAsync<Order>();
    return new CloudEvent(
        source: "/myapp/orders",
        type: "Orders.Created",
        jsonSerializableData: order)
    {
        Subject = $"/orders/{order!.OrderId}",
        Id = Guid.NewGuid().ToString()
    };
}

# Route Event Grid events to a Service Bus topic
az eventgrid event-subscription create \
  --name order-to-servicebus \
  --source-resource-id <custom-topic-id> \
  --endpoint-type servicebustopic \
  --endpoint /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.ServiceBus/namespaces/<namespace>/topics/<topic-name> \
  --included-event-types Orders.Created Orders.Updated \
  --subject-begins-with /orders/

# Route to Event Hub for stream analytics ingestion
az eventgrid event-subscription create \
  --name resource-changes-to-eventhub \
  --source-resource-id /subscriptions/<sub> \
  --endpoint-type eventhub \
  --endpoint /subscriptions/<sub>/resourceGroups/<rg>/providers/\
Microsoft.EventHub/namespaces/<namespace>/eventhubs/<hub-name> \
  --included-event-types Microsoft.Resources.ResourceWriteSuccess \
                          Microsoft.Resources.ResourceDeleteSuccess

// Function triggered by blob-created event from Event Grid
[Function("ProcessUploadedDocument")]
public async Task Run(
    [EventGridTrigger] EventGridEvent eventGridEvent,
    [BlobInput("{data.url}", Connection = "StorageConnection")] Stream blobStream)
{
    if (eventGridEvent.EventType != "Microsoft.Storage.BlobCreated") return;

    var data = eventGridEvent.Data!.ToObjectFromJson<StorageBlobCreatedEventData>();

    // Only process PDFs from the 'uploads' container
    if (!data.Url.Contains("/uploads/") || data.ContentType != "application/pdf")
        return;

    _logger.LogInformation("Processing uploaded PDF: {Url}", data.Url);

    // Call Azure Document Intelligence
    var result = await _documentClient.AnalyzeDocumentAsync(blobStream);

    // Store extracted data to Cosmos DB
    await _cosmosContainer.UpsertItemAsync(new
    {
        id = data.BlobUrl.Split('/').Last(),
        extractedText = result.Content,
        uploadedAt = eventGridEvent.EventTime,
        blobUrl = data.Url
    });
}

using Azure.Messaging.EventGrid;
using Azure;

// With access key
var client = new EventGridPublisherClient(
    new Uri("https://order-events.<region>.eventgrid.azure.net/api/events"),
    new AzureKeyCredential("<topic-key>"));

// With Managed Identity (recommended)
var client = new EventGridPublisherClient(
    new Uri("https://order-events.<region>.eventgrid.azure.net/api/events"),
    new DefaultAzureCredential());

// Publish Event Grid schema events
var events = new List<EventGridEvent>
{
    new EventGridEvent(
        subject:     "/orders/ORD-12345",
        eventType:   "Orders.Created",
        dataVersion: "1.0",
        data: new
        {
            orderId  = "ORD-12345",
            amount   = 299.99,
            region   = "EU-West",
            customer = new { id = "C001", email = "user@example.com" }
        }),
    new EventGridEvent(
        subject:     "/orders/ORD-12346",
        eventType:   "Orders.Created",
        dataVersion: "1.0",
        data: new { orderId = "ORD-12346", amount = 149.00, region = "US-East" })
};
await client.SendEventsAsync(events);

// Publish CloudEvents (recommended)
var cloudEvents = new List<CloudEvent>
{
    new CloudEvent(
        source:               "/myapp/orders",
        type:                 "Orders.Created",
        jsonSerializableData: new { orderId = "ORD-12347", amount = 99.99 })
    {
        Subject = "/orders/ORD-12347",
        Id      = Guid.NewGuid().ToString(),
        Time    = DateTimeOffset.UtcNow
    }
};
await client.SendCloudEventsAsync(cloudEvents);

# Publish a CloudEvent via curl
curl -X POST https://order-events.<region>.eventgrid.azure.net/api/events \
  -H "Content-Type: application/cloudevents+json" \
  -H "aeg-sas-key: <topic-access-key>" \
  -d '{
    "specversion": "1.0",
    "type": "Orders.Created",
    "source": "/myapp/orders",
    "id": "unique-event-id-1",
    "time": "2026-05-04T10:00:00Z",
    "subject": "/orders/ORD-12345",
    "datacontenttype": "application/json",
    "data": { "orderId": "ORD-12345", "amount": 299.99 }
  }'

// Publish to a domain — topic name is per-tenant
var domainClient = new EventGridPublisherClient(
    new Uri("https://my-domain.<region>.eventgrid.azure.net/api/events"),
    new DefaultAzureCredential());

// Include topic in the event — routes to tenant's topic automatically
var events = new[]
{
    new EventGridEvent(
        subject:     "/invoices/INV-001",
        eventType:   "Invoice.Created",
        dataVersion: "1.0",
        data:        new { invoiceId = "INV-001", amount = 500.0 })
    {
        // Topic routes to tenant-a's topic within the domain
        Topic = "tenant-a"
    },
    new EventGridEvent(
        subject:     "/invoices/INV-002",
        eventType:   "Invoice.Created",
        dataVersion: "1.0",
        data:        new { invoiceId = "INV-002", amount = 750.0 })
    {
        Topic = "tenant-b"
    }
};
await domainClient.SendEventsAsync(events);

AzureDiagnostics
| where ResourceType == "TOPICS" or ResourceType == "SYSTEMTOPICS"
| where OperationName == "DeadLetterEvent"
| where TimeGenerated > ago(24h)
| project TimeGenerated, Resource, subject_s, eventType_s,
          deadLetterReason_s, deliveryAttemptCount_d
| order by TimeGenerated desc

AzureMetrics
| where ResourceType == "MICROSOFT.EVENTGRID/TOPICS"
| where MetricName in ("DeliveryFailureCount", "DeadLetteredCount")
| where TimeGenerated > ago(1h)
| summarize TotalFailures = sum(Total) by bin(TimeGenerated, 5m), MetricName, Resource
| where TotalFailures > 0
| order by TimeGenerated desc