Create and route custom events with the Azure portal and Event Grid

Azure Event Grid is an eventing service for the cloud. In this article, you use the Azure portal to create a custom topic, subscribe to the topic, and trigger the event to view the result. Typically, you send events to an endpoint that responds to the event, such as, a webhook or Azure Function. However, to simplify this article, you send the events to a URL that merely collects the messages. You create this URL by using an open source, third-party tool called RequestBin.

Note

RequestBin is an open source tool that is not intended for high throughput usage. The use of the tool here is purely demonstrative. If you push more than one event at a time, you might not see all of your events in the tool.

When you are finished, you see that the event data has been sent to an endpoint.

Event data

If you don't have an Azure subscription, create a free account before you begin.

Create a resource group

Event Grid topics are Azure resources, and must be placed in an Azure resource group. The resource group is a logical collection into which Azure resources are deployed and managed.

  1. In the left navigation, select Resource Groups. Then, select Add.

    Create resource group

  2. Set the resource group name to gridResourceGroup and the location to westus2. Select Create.

    Provide resource group values

Create a custom topic

A topic provides a user-defined endpoint that you post your events to.

  1. To create a topic in your resource group, select More services and search for event grid. Select Event Grid Topics from the available options.

    Create event grid topic

  2. Select Add.

    Add event grid topic

  3. Provide a name for the topic. The topic name must be unique because it is represented by a DNS entry. For the preview release, Event Grid supports westus2 and westcentralus locations. Select the resource group you created earlier. Select Create.

    Provide event grid topic values

  4. After the topic has been created, select Refresh to see the topic.

    See event grid topic

Create a message endpoint

Before subscribing to the topic, let's create the endpoint for the event message. Rather than write code to respond to the event, let's create an endpoint that collects the messages so you can view them. RequestBin is an open source, third-party tool that enables you to create an endpoint, and view requests that are sent to it. Go to RequestBin, and click Create a RequestBin. Copy the bin URL, because you need it when subscribing to the topic.

Subscribe to a topic

You subscribe to a topic to tell Event Grid which events you want to track.

  1. To create an Event Grid subscription, again select More Services and search for event grid. Select Event Grid Subscriptions from the available options.

    Create event grid subscription

  2. Select + Event Subscription.

    Add event grid subscription

  3. Provide a unique name for your event subscription. For the topic type, select Event Grid Topics. For the instance, select the custom topic you created. Provide the URL from RequestBin as the endpoint for event notification. When finished providing values, select Create.

    Provide event grid subscription value

Now, let's trigger an event to see how Event Grid distributes the message to your endpoint. To simplify this article, use Cloud Shell to send sample event data to the topic. Typically, an application or Azure service would send the event data.

Launch Azure Cloud Shell

The Azure Cloud Shell is a free interactive shell that you can use to run the steps in this article. It has common Azure tools preinstalled and configured to use with your account. Just click the Copy to copy the code, paste it into the Cloud Shell, and then press enter to run it. There are a few ways to launch the Cloud Shell:

Click Try It in the upper right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser. https://shell.azure.com/bash
Click the Cloud Shell button on the menu in the upper right of the Azure portal. Cloud Shell in the portal

Send an event to your topic

First, let's get the URL and key for the topic. Use your topic name for <topic_name>.

endpoint=$(az eventgrid topic show --name <topic_name> -g gridResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name <topic_name> -g gridResourceGroup --query "key1" --output tsv)

The following example gets sample event data:

body=$(eval echo "'$(curl https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/event-grid/customevent.json)'")

If you echo "$body" you can see the full event. The data element of the JSON is the payload of your event. Any well-formed JSON can go in this field. You can also use the subject field for advanced routing and filtering.

CURL is a utility that performs HTTP requests. In this article, we use CURL to send the event to our topic.

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

You have triggered the event, and Event Grid sent the message to the endpoint you configured when subscribing. Browse to the RequestBin URL that you created earlier. Or, click refresh in your open RequestBin browser. You see the event you just sent.

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/{topic}"
}]

Clean up resources

If you plan to continue working with this event, do not clean up the resources created in this article. If you do not plan to continue, delete the resources you created in this article.

Select the resource group, and select Delete resource group.

Next steps

Now that you know how to create topics and event subscriptions, learn more about what Event Grid can help you do: