Publish events to Azure Event Grid custom topics by using access keys

An Event Grid custom topic is an endpoint that your applications send their own events to, so that Event Grid can route those events to interested subscribers. This article shows you how to publish events to a custom topic by using access keys, which authenticate your requests without setting up Microsoft Entra ID. You get the topic endpoint and access key, format an event payload, send a sample event, and review the response.

The Service Level Agreement (SLA) applies only to posts that match the expected format.

Prerequisites

• An Azure Event Grid custom topic. To create one, see Send custom events to a web endpoint by using the Azure portal.
• Azure CLI, Azure PowerShell, or access to the Azure portal to retrieve the topic endpoint and access key.
• A tool that can send HTTP POST requests, such as curl.

Get the topic endpoint

To publish events to a custom topic, send an HTTP POST request by using the following URI format: https://<topic-endpoint>?api-version=2018-01-01. For example, a valid URI is: https://exampletopic.westus2-1.eventgrid.azure.net/api/events?api-version=2018-01-01. To get the endpoint for a custom topic, use the Azure portal, Azure CLI, or Azure PowerShell.

az eventgrid topic show --name <topic-name> -g <topic-resource-group> --query "endpoint"

(Get-AzEventGridTopic -ResourceGroupName <topic-resource-group> -Name <topic-name>).Endpoint

Get the access key

In the request, include a header value named aeg-sas-key that contains a key for authentication. For example, a valid header value is aeg-sas-key: xxxxxxxxxxxxxxxxxxxxxxx. To get the key for a custom topic, use the Azure portal, Azure CLI, or Azure PowerShell.

az eventgrid topic key list --name <topic-name> -g <topic-resource-group> --query "key1"

(Get-AzEventGridTopicKey -ResourceGroupName <topic-resource-group> -Name <topic-name>).Key1

Format the event payload

Format each event as a JSON object. The top-level fields are the same as standard resource-defined events, and the data property holds the properties that are unique to your custom topic. As the publisher, you define the contents of the data object. For a description of each property, see Azure Event Grid event schema.

[
  {
    "id": string,
    "eventType": string,
    "subject": string,
    "eventTime": string-in-date-time-format,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string
  }
]

Keep these size limits in mind when you build the payload:

• The event array can have a total size of up to 1 MB.
• The maximum size for a single event is 1 MB. Events over 64 KB incur charges in 64-KB increments.
• A batch can contain a maximum of 5,000 events.

The following example shows a valid event payload:

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "dataVersion": "1.0"
}]

Send a sample event

This section shows how to send a sample event to the custom topic.

endpoint=$(az eventgrid topic show --name <topic name> -g <resource group name> --query "endpoint" --output tsv)

key=$(az eventgrid topic key list --name <topic name> -g <resource group name> --query "key1" --output tsv)

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/motorcycles", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "make": "Ducati", "model": "Monster"},"dataVersion": "1.0"} ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

$resourceGroupName = "<resource group name>"
$topicName = "<topic name>"

$endpoint = (Get-AzEventGridTopic -ResourceGroupName $resourceGroupName -Name $topicName).Endpoint

$keys = Get-AzEventGridTopicKey -ResourceGroupName $resourceGroupName -Name $topicName

$eventID = Get-Random 99999
#Date format should be SortableDateTimePattern (ISO 8601)
$eventDate = Get-Date -Format s

#Construct body using Hashtable
$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/motorcycles"
    eventTime= $eventDate
    data= @{
        make="Ducati"
        model="Monster"
    }
    dataVersion="1.0"
}

#Use ConvertTo-Json to convert event body from Hashtable to JSON Object
#Append square brackets to the converted JSON payload since they are expected in the event's JSON payload syntax
$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

Review the response

After you post to the topic endpoint, you receive a response. The response is a standard HTTP response code. Some common responses are:

For errors, the message body uses the following format:

{
    "error": {
        "code": "<HTTP status code>",
        "message": "<description>",
        "details": [{
            "code": "<HTTP status code>",
            "message": "<description>"
    }]
  }
}

Related content

• Monitor Event Grid message delivery: Learn how to track and troubleshoot event deliveries.
• Event Grid security and authentication: Understand how to secure your events with authentication keys.
• Event Grid subscription schema: Step-by-step guidance on creating an Event Grid subscription.