Event Grid Custom Topics

Azure Event Grid supports three types of topics — System Topics, Custom Topics, and Partner Topics. System Topics and Custom Topics are the two most commonly used in day-to-day development. Each serves a distinct purpose depending on whether the event source is an Azure service or a custom application.

System Topics

A System Topic is a built-in topic that Azure creates automatically for supported Azure services. When an Azure service such as Blob Storage, Azure Container Registry, or Azure IoT Hub emits events, those events flow through a System Topic.

Developers do not create the topic itself. Azure creates it in the background. A developer only creates a subscription on top of the existing System Topic to start receiving events.

How a System Topic Works

+---------------------+        Events         +----------------------+
|  Azure Blob Storage |  ─────────────────->  |  System Topic        |
|  (Event Source)     |                        |  (Created by Azure   |
+---------------------+                        |   automatically)     |
                                               +----------+-----------+
                                                          |
                                    +─────────────────────+──────────────────+
                                    |                     |                  |
                         +──────────+──────+   +──────────+──────+  +────────+──────+
                         | Subscription 1  |   | Subscription 2  |  | Subscription 3|
                         | Azure Function  |   | Logic App       |  | Storage Queue |
                         +─────────────────+   +─────────────────+  +───────────────+

Azure Services That Support System Topics

Creating a System Topic – Step-by-Step (Azure Portal)

1. Open the Azure Portal and navigate to the Azure Blob Storage account
2. Select Events from the left menu
3. Click + Event Subscription
4. Azure automatically creates a System Topic in the background
5. Fill in the subscription name, filter by event type, and select a handler endpoint
6. Click Create

The System Topic appears in the resource group as a resource of type "Event Grid System Topic" after the first subscription is created.

System Topic – Important Notes

• System Topics are free to create. Cost occurs only when events are delivered.
• One System Topic per Azure resource (one per Storage account, one per IoT Hub, etc.)
• System Topics can be viewed, managed, and deleted through the Azure Portal
• Deleting a System Topic deletes all subscriptions on it

Custom Topics

A Custom Topic is a topic that a developer creates manually for a custom application. When an application built outside of Azure needs to publish events to Event Grid, a Custom Topic provides the endpoint.

Custom Topics give full control over the event schema and the event types published. Any application that can make an HTTPS POST request can publish events to a Custom Topic.

How a Custom Topic Works

+─────────────────────+     POST /api/events     +──────────────────────+
|  Custom Application |  ──────────────────────> |  Custom Topic        |
|  (E-commerce App,   |  (with SAS Key or AAD    |  (created manually   |
|   Mobile Backend,   |   token in header)        |   by developer)      |
|   IoT Device App)   |                           +──────────┬───────────+
+─────────────────────+                                      |
                                                  +──────────+──────────+
                                                  |                     |
                                       +──────────+──────+   +──────────+──────+
                                       | Subscription 1  |   | Subscription 2  |
                                       | Handler: Func   |   | Handler: Webhook|
                                       +─────────────────+   +─────────────────+

Creating a Custom Topic – Step-by-Step (Azure Portal)

1. In the Azure Portal, search for Event Grid Topics
2. Click + Create
3. Fill in Subscription, Resource Group, Name, Region, and Event Schema
4. Click Review + Create, then Create
5. After creation, copy the Topic Endpoint URL and the Access Key
6. Use this URL and key in the application to publish events

Publishing an Event to a Custom Topic – Example

HTTP POST https://myorders.eastus-1.eventgrid.azure.net/api/events
Headers:
  Content-Type: application/json
  aeg-sas-key: <your-access-key>

Body:
[
  {
    "id": "order-001",
    "eventType": "App.OrderPlaced",
    "subject": "/orders/ORD-9821",
    "eventTime": "2024-06-01T10:00:00Z",
    "data": {
      "orderId": "ORD-9821",
      "customer": "Alice",
      "amount": 250.00
    },
    "dataVersion": "1.0"
  }
]

The event type in a Custom Topic is freely defined. The convention is to use a reverse-domain format such as "App.OrderPlaced" or "Inventory.StockLow" for clarity.

System Topics vs Custom Topics – Side-by-Side Comparison

Practical Example: System Topic and Custom Topic Together

Consider an e-commerce application hosted on Azure.

SYSTEM TOPIC USE CASE:
  Action: Customer uploads a product image to Blob Storage
  System Topic: Created by Azure for the Storage account
  Subscription: Filters for BlobCreated + subject ends with ".jpg"
  Handler: Azure Function generates a thumbnail

CUSTOM TOPIC USE CASE:
  Action: Backend application places a new order
  Custom Topic: Created by developer (named "orders-topic")
  Publisher: Order service POSTs an "App.OrderPlaced" event
  Subscription 1: Inventory service receives and reduces stock
  Subscription 2: Email service sends an order confirmation

Both topic types work together in the same application. Azure handles infrastructure events through System Topics, and custom business logic events flow through Custom Topics.

Topic Endpoint Security

Custom Topics require authentication when publishing events. Two authentication methods are available.

Method 1 – SAS Key (Simple Access)

A shared access signature key is included in the HTTP header using the field aeg-sas-key. This is the quickest method but requires careful key management and rotation.

Method 2 – Azure Active Directory (Recommended)

Applications authenticate using an Azure AD token and include it as a Bearer token in the Authorization header. This method uses managed identities and role-based access control, which is more secure than shared keys.

Summary

System Topics and Custom Topics serve different event sources but work the same way from the subscription side. System Topics require no extra setup for supported Azure services. Custom Topics give full flexibility for any application that needs to participate in event-driven workflows.