Event Grid: Custom Topics and Event Domains

While system topics let you react to Azure service events, custom topics allow you to publish your own events from any application. Event domains take this further by providing a single management endpoint for thousands of related topics. This lesson covers how to create and use custom topics, how to secure them, and when to use event domains for large-scale scenarios.

---

Custom Topics

A custom topic is an Event Grid endpoint that you create to publish events from your own applications. Any service — a web API, a background worker, an IoT device — can send events to a custom topic using HTTP POST.

Creating a Custom Topic

az eventgrid topic create \
  --name app-events \
  --resource-group rg-messaging \
  --location uksouth \
  --input-schema eventgridschema

After creation, the topic has an endpoint URL and two access keys:

az eventgrid topic show --name app-events --resource-group rg-messaging --query "endpoint"
az eventgrid topic key list --name app-events --resource-group rg-messaging

Publishing Events

import { EventGridPublisherClient, AzureKeyCredential } from '@azure/eventgrid';

const client = new EventGridPublisherClient(
  'https://app-events.uksouth-1.eventgrid.azure.net/api/events',
  'EventGrid',
  new AzureKeyCredential(topicKey)
);

await client.send([
  {
    eventType: 'App.User.Registered',
    subject: '/users/user-123',
    dataVersion: '1.0',
    data: {
      userId: 'user-123',
      email: 'alice@example.com',
      plan: 'premium',
    },
  },
]);

You can publish up to 5,000 events per request (or 1 MB total). Events are delivered to subscribers within seconds.

Subscribing to a Custom Topic

# Subscribe an Azure Function to the custom topic
az eventgrid event-subscription create \
  --name handle-registrations \
  --source-resource-id /subscriptions/{sub-id}/resourceGroups/rg-messaging/providers/Microsoft.EventGrid/topics/app-events \
  --endpoint /subscriptions/{sub-id}/resourceGroups/rg-messaging/providers/Microsoft.Web/sites/myApp/functions/OnUserRegistered \
  --endpoint-type azurefunction \
  --included-event-types App.User.Registered

---

Authentication and Security

Access Keys

Every custom topic has two access keys. Include the key in the aeg-sas-key header when publishing. Rotate keys regularly and store them in Azure Key Vault.

SAS Tokens

For temporary, scoped access, generate a Shared Access Signature (SAS) token:

az eventgrid topic generate-sas --name app-events --resource-group rg-messaging \
  --expiration-date-utc "2025-12-31T23:59:59Z"

Managed Identity

For Azure-to-Azure scenarios, use managed identities to authenticate without storing keys:

import { DefaultAzureCredential } from '@azure/identity';

const client = new EventGridPublisherClient(
  topicEndpoint,
  'EventGrid',
  new DefaultAzureCredential()
);

Webhook Validation

When subscribing an HTTP webhook to Event Grid, the endpoint must prove ownership by responding to a validation handshake:

1. Event Grid sends a SubscriptionValidation event with a validationCode
2. Your endpoint returns the code in the response body
3. Event Grid confirms the subscription

This prevents anyone from subscribing arbitrary endpoints to your topics.

---

Event Domains