Post to custom topic for Azure Event Grid

This article describes how to post an event to a custom topic. It shows the format of the post and event data. The Service Level Agreement (SLA) only applies to posts that match the expected format.

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Endpoint

When sending the HTTP POST to a custom topic, use the 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 with Azure CLI, use:

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

To get the endpoint for a custom topic with Azure PowerShell, use:

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

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: VXbGWce53249Mt8wuotr0GPmyJ/nDT4hgdEj9DpBeRr38arnnm5OFg==.

To get the key for a custom topic with Azure CLI, use:

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

To get the key for a custom topic with PowerShell, use:

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

Event data

For custom topics, the top-level data contains the same fields as standard resource-defined events. One of those properties is a data property that contains properties unique to the custom topic. As event publisher, you determine the properties for that data object. Use the following schema:

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

For a description of these properties, see Azure Event Grid event schema. When posting events to an event grid topic, the array can have a total size of up to 1 MB. Each event in the array is limited to 64 KB.

For example, a valid event data schema is:

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

Response

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

Result Response
Success 200 OK
Event data has incorrect format 400 Bad Request
Invalid access key 401 Unauthorized
Incorrect endpoint 404 Not Found
Array or event exceeds size limits 413 Payload Too Large

For errors, the message body has the following format:

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

Next steps