Skip to content

Topics

Jump to bottom
Paul Mcilreavy edited this page Dec 22, 2025 · 2 revisions

Topics are the core concept in Azure Event Grid. Each topic listens on a unique HTTPS port and can have multiple subscribers.

Topic Configuration

See Configuration for the complete list of topic settings.

Disabling Topics

You can disable a topic by setting disabled: true. Disabled topics are not started and cannot receive events:

{
  "topics": [
    {
      "name": "DisabledTopic",
      "port": 60102,
      "disabled": true
    }
  ]
}

HTTPS Requirements

Azure Event Grid only accepts connections over HTTPS, so the simulator only supports HTTPS too.

The simulator will attempt to use the dotnet development certificate to secure each topic port. You can ensure that this certificate is installed and trusted by running:

dotnet dev-certs https --trust

You can also generate a certificate file (suitable for using with a Docker container):

dotnet dev-certs https --export-path ./docker/azureEventGridSimulator.pfx --password Y0urSup3rCrypt1cPa55w0rd!

Subscribers

A topic can have 0 to n subscribers. When a request is received for a topic, the events will be forwarded to each of the subscribers with the addition of an aeg-event-type: Notification header.

If the message contains multiple events, they will be sent to each subscriber one at a time inline with the Azure Event Grid behaviour. "Event Grid sends the events to subscribers in an array that has a single event. This behavior may change in the future."

See the subscriber type pages for configuration details:

Key Validation

The simulator supports multiple authentication methods:

Using aeg-sas-key (Simple)

Just set the value of the aeg-sas-key header to the same key value configured for the topic.

curl -H "aeg-sas-key: TheLocal+DevelopmentKey=" ...

Using aeg-sas-token (More Secure)

Using an aeg-sas-token is more secure as the key is hashed and includes expiration. More information on SAS tokens can be found in the Azure documentation.

curl -H "aeg-sas-token: r=https://...&e=2024-01-01T00:00:00Z&s=..." ...

Using Authorization Header

The standard Authorization header with SharedAccessSignature scheme is also supported:

curl -H "Authorization: SharedAccessSignature r=https://...&e=2024-01-01T00:00:00Z&s=..." ...

Validation Behavior

If the incoming request contains any of the authentication headers and there is a key configured for the topic, the simulator will validate the key and reject the request if the value in the header is not valid.

If you want to skip validation, set the key to null in appsettings.json.

Size Validation

Azure Event Grid imposes certain size limits:

  • Overall message body: <= 1,048,576 bytes (1 MB)
  • Each individual event: <= 1,048,576 bytes (1 MB)

Note: Testing has shown that the actual limits may be slightly higher: 1,536,000 bytes (1.5 MB) for the overall message body and 1,049,600 bytes (1 MB) for each individual event.

Schema Support

Topics support two event schemas. See Schema Support for details on:

  • EventGrid Schema
  • CloudEvents v1.0 Schema

Input Schema

The inputSchema setting specifies the expected event schema for incoming requests:

  • EventGridSchema - Azure Event Grid native schema
  • CloudEventV1_0 - CloudEvents v1.0 specification

If not specified, the schema is auto-detected from the request.

Output Schema

The outputSchema setting specifies how events are delivered to subscribers:

  • EventGridSchema - Deliver in Azure Event Grid format
  • CloudEventV1_0 - Deliver in CloudEvents format

If not specified, events are delivered in the same schema they were received in.

API Endpoints

Each topic exposes the following endpoints:

Endpoint Method Description
/api/events?api-version=2018-01-01 POST Publish events to the topic
/api/health GET Health check endpoint (returns "OK")
/validate?id={code} GET Subscription validation endpoint
/dashboard GET Dashboard UI (if enabled)

Health Check

The health check endpoint can be used for container orchestration and load balancer health probes:

curl -k https://localhost:60101/api/health
# Returns: OK

Related Topics

Getting Started

Subscribers

Features

Deployment

Reference

Clone this wiki locally