In this quickstart, you create a topic, create a subscription to that topic using a Webhook endpoint, trigger a sample event, and then view the result. Typically, you send events to an endpoint that processes the event data and takes actions. However, to simplify this tutorial, you send the events to a web app that collects and displays the messages.

Prerequisites

• If you don't have an Azure subscription, create anAzure free account before you begin.
• If you're new Azure Event Grid, seeEvent Grid overview.

Register the Event Grid resource provider

Unless you've used Event Grid before, you'll need to register the Event Grid resource provider. If you’ve used Event Grid before, skip to the next section.

In the Azure portal, do the following steps:

1. On the left menu, selectSubscriptions.

2. Select thesubscription you want to use for Event Grid from the subscription list.

3. On theSubscription page, selectResource providers underSettings on the left menu.

4. Search forMicrosoft.EventGrid, and confirm that theStatus isNot Registered.

5. SelectMicrosoft.EventGrid in the provider list.

6. SelectRegister on the command bar.

   

7. Refresh to make sure the status ofMicrosoft.EventGrid is changed toRegistered.

   

Create a custom topic

An Event Grid topic provides a user-defined endpoint that you post your events to.

1. Sign in toAzure portal.

2. In the search bar at the topic, typeEvent Grid Topics, and then selectEvent Grid Topics from the drop-down list.

   

3. On theEvent Grid Topics page, select+ Create on the toolbar.

   

4. On theCreate Topic page, follow these steps:

   1. Select your Azuresubscription.

   2. Select an existing resource group or selectCreate new, and enter aname for theresource group.

   3. Provide a uniquename for the custom topic. The topic name must be unique because it's represented by a DNS entry. Don't use the name shown in the image. Instead, create your own name - it must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and-.

   4. Select alocation for the Event Grid topic.

   5. SelectReview + create at the bottom of the page.

      

   6. On theReview + create tab of theCreate topic page, selectCreate.

      

5. After the deployment succeeds, selectGo to resource to navigate to theEvent Grid Topic page for your topic. Keep this page open. You use it later in the quickstart.

   

   Note

   To keep the quickstart simple, you'll be using only theBasics page to create a topic. For detailed steps about configuring network, security, and data residency settings on other pages of the wizard, seeCreate a custom topic.

Create a message endpoint

Before you create a subscription for the custom topic, create an endpoint for the event message. Typically, the endpoint takes actions based on the event data. To simplify this quickstart, you deploy aprebuilt web app that displays the event messages. The deployed solution includes an App Service plan, an App Service web app, and source code from GitHub.

1. In the article page, selectDeploy to Azure to deploy the solution to your subscription. In the Azure portal, provide values for the parameters.

   

2. On theCustom deployment page, do the following steps:

   1. ForResource group, select an existing resource group or create a resource group.

   2. ForSite Name, enter a name for the web app.

   3. ForHosting plan name, enter a name for the App Service plan to use for hosting the web app.

   4. SelectReview + create.

      

3. On theReview + create page, selectCreate.

4. The deployment might take a few minutes to complete. Select Alerts (bell icon) in the portal, and then selectGo to resource group.

   

5. On theResource group page, in the list of resources, select the web app (contosoegriviewer in the following example) that you created.

   

6. On theApp Service page for your web app, select the URL to navigate to the web site. The URL should be in this format:https://<your-site-name>.azurewebsites.net.

   

7. Confirm that you see the site but no events have been posted to it yet.

   

Subscribe to custom topic

You subscribe to an Event Grid topic to tell Event Grid which events you want to track, and where to send the events.

1. Now, on theEvent Grid Topic page for your custom topic, select+ Event Subscription on the toolbar.

   

2. On theCreate Event Subscription page, follow these steps:

   1. Enter aname for the event subscription.

   2. SelectWeb Hook for theEndpoint type.

   3. ChooseSelect an endpoint.

      

   4. For the web hook endpoint, provide the URL of your web app and addapi/updates to the home page URL. SelectConfirm Selection.

      

   5. Back on theCreate Event Subscription page, selectCreate.

3. View your web app again, and notice that a subscription validation event has been sent to it. Select the eye icon to expand the event data. Event Grid sends the validation event so the endpoint can verify that it wants to receive event data. The web app includes code to validate the subscription.

   

Send an event to your topic

Now, let's trigger an event to see how Event Grid distributes the message to your endpoint. Use either Azure CLI or PowerShell to send a test event to your custom topic. Typically, an application or Azure service would send the event data.

The first example uses Azure CLI. It gets the URL and key for the custom topic, and sample event data. Use your custom topic name for<topic name>. It creates sample event data. Thedata 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 sends HTTP requests.

Azure CLI

1. In the Azure portal, selectCloud Shell. The Cloud Shell opens in the bottom pane of the web browser.

   

2. If the Cloud Shell opens a PowerShell session, selectSwitch to Bash in the top-left corner of the Cloud Shell window. If not, continue to the next step.

   

3. Run the following command to get theendpoint for the topic: After you copy and paste the command, update thetopic name andresource group name before you run the command. You publish sample events to this topic endpoint.

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

4. Run the following command to get thekey for the custom topic: After you copy and paste the command, update thetopic name andresource group name before you run the command. It's the primary key of the Event Grid topic. To get this key from the Azure portal, switch to theAccess keys tab of theEvent Grid Topic page. To be able post an event to a custom topic, you need the access key.

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

5. Copy the following statement with the event definition, and pressENTER.

   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"} ]'

6. Run the followingCurl command to post the event: In the command,aeg-sas-key header is set to the access key you got earlier.

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

Azure PowerShell

The second example uses PowerShell to do similar steps.

1. In the Azure portal, selectCloud Shell (alternatively go tohttps://shell.azure.com/). The Cloud Shell opens in the bottom pane of the web browser.

   

2. In theCloud Shell, selectPowerShell in the top-left corner of the Cloud Shell window. See the sampleCloud Shell window image in the Azure CLI section.

3. Set the following variables. After you copy and paste each command, update thetopic name andresource group name before you run the command:

   Resource group:

   $resourceGroupName = "<resource group name>"

   Event Grid topic name:

   $topicName = "<topic name>"

4. Run the following commands to get theendpoint and thekeys for the topic:

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

5. Prepare the event. Copy and run the statements in the Cloud Shell window.

   $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)+"]"

6. Use theInvoke-WebRequest cmdlet to send the event.

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

Verify in the Event Grid Viewer

You've triggered the event, and Event Grid sent the message to the endpoint you configured when subscribing. View your web app to see the event you just sent.

Clean up resources

If you plan to continue working with this event, don't clean up the resources created in this article. Otherwise, delete the resources you created in this article.

1. SelectResource Groups on the left menu. If you don't see it on the left menu, selectAll Services on the left menu, and selectResource Groups.

   

2. Select the resource group to launch theResource Group page.

3. SelectDelete resource group on the toolbar.

4. Confirm deletion by entering the name of the resource group, and selectDelete.

   The other resource group you see in the image was created and used by the Cloud Shell window. Delete it if you don't plan to use the Cloud Shell window later.

Related content

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

• Route Blob storage events to a custom web endpoint
• Azure Event Grid samples for .NET
• Azure Event Grid samples for Java