Quickstart - Subscribe to Azure Communication Services Events - An Azure Communication Services quickstart

Article
10/25/2024

This article explains how to subscribe to events from Azure Communication Services through the portal, Azure CLI, PowerShell, and .NET SDK.

You can set up event subscriptions for Communication Services resources through the Azure portal, Azure CLI, PowerShell, or with the Azure Event Grid Management SDK.

This quickstart describes the process of setting up a webhook as a subscriber for SMS events from Azure Communication Services. For a full list of events, see Azure Communication Services as an Azure Event Grid source.

Prerequisites

An Azure account with an active subscription. Create an account for free.
An Azure Communication Services resource.
Create a Webhook to receive events. See Webhook Event Delivery.

Register the Event Grid resource provider

This article describes how to register the Event Grid resource provider. If you used Event Grid before in the same subscription, skip to the next section.

In the Azure portal, do the following steps:

On the left menu, select Subscriptions.
Select the Subscription you want to use for Event Grid from the subscription list.
On the Subscription page, select Resource providers under Settings on the left menu.
Search for Microsoft.EventGrid, and confirm that the Status is Not Registered.
Select Microsoft.EventGrid in the provider list.
Select Register on the command bar.
Refresh to make sure the status of Microsoft.EventGrid is changed to Registered.

Create event subscription

To create an Event subscription for Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select the Communication Services resource.

Select the Events tab from the left menu.
Select + Event Subscription.

On the Create Event Subscription page, follow these steps:
1. Enter a name for the event subscription.
2. Enter a name for the System topic name.
3. Select the event types that you want to receive on the event subscription.
  
  For more information, see Communication Services Events.
4. Select the Endpoint Type as Web Hook.
5. Select Configure an Endpoint
6. Enter the link to the webhook and select Confirm Selection.
7. In the Filters tab, add the names of the event types you want to filter in the subscription. Add any context attribute filters you want to use in the subscription. Then, select Next: Additional features at the bottom of the page.
8. To enable dead lettering and customize retry policies, select Additional Features.
9. When done, select Create.

Update event subscription

This section shows how to update an Event subscription for Azure Communication Services to update the events you want to receive via Webhook.

To update an Event subscription for Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select the Communication Services resource.

Select the Events tab from the left menu.
Select Event Subscriptions and select the Event subscription you want to update.
On the Event Subscription page, select the Filters tab. Select the event types that you want to receive on the event subscription.
To enable dead lettering and customize retry policies, select Additional Features.
To update the webhook to receive events, select Change next to the webhook link and enter the new webhook endpoint.
When done, select Save.

Delete event subscription

To delete an Event subscription for Azure Communication Services, follow these steps.

To delete an Event subscription for Azure Communication Services resource, first sign in to the Azure portal. In the upper-left corner of the page, select the Communication Services resource.

Select the Events tab from the left menu.
Select Event Subscriptions and select the Event subscription you want to delete.
On the Event Subscription page, Select Delete from the top of the page.

Next steps

For a list of Communication Services events, see Communication Services Events.
For a list of supported event handlers, see Event handlers.
For information about event delivery and retries, see Event Grid message delivery and retry.
For an introduction to Event Grid, see About Event Grid.

Prerequisites

An Azure account with an active subscription. Create an account for free.
Install Azure CLI.
An Azure Communication Services resource.
Create a Webhook to receive events. See Webhook Event Delivery.

Register the Event Grid resource provider

This article describes how to register the Event Grid resource provider. If you used Event Grid before in the same subscription, skip to the next section.

Run the following command to register the provider:

az provider register --namespace Microsoft.EventGrid

It might take a moment for the registration to finish. To check the status, run the following command:
```
az provider show --namespace Microsoft.EventGrid --query "registrationState"
```
When registrationState is Registered, you're ready to continue.

Create event subscription

To create event subscriptions for Azure Communication Services resource, sign in to Azure CLI. You can sign in running the az login command from the terminal, then provide your credentials.

To create an event subscription using the Azure CLI, use the az eventgrid event-subscription create command:

az eventgrid event-subscription create 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

For a list of Communication Services events, see Communication Services Events.

List event subscriptions

To list all the existing event subscriptions set up for an Azure Communication Services resource using the Azure CLI, use the az eventgrid event-subscription list command.

az eventgrid event-subscription list 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

Update event subscription

To update an existing event subscription using the Azure CLI, use the az eventgrid event-subscription update command.

az eventgrid event-subscription update 
    --name EventsWebhookSubscription
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>
    --included-event-types Microsoft.Communication.SMSReceived Microsoft.Communication.SMSDeliveryReportReceived Microsoft.Communication.ChatMessageReceived
    --endpoint-type webhook 
    --endpoint https://azureeventgridviewer.azurewebsites.net/api/updates

Delete event subscription

To delete an existing event subscription using the Azure CLI, use the az eventgrid event-subscription delete command.

az eventgrid event-subscription delete 
    --name EventsWebhookSubscription 
    --source-resource-id /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>

Next steps

For information about other commands, see Azure Event Grid CLI.

Prerequisites

An Azure account with an active subscription. Create an account for free.
The latest version .NET Core SDK for your operating system.
The latest version of the .NET Microsoft Azure Event Grid Management SDK.
The latest version of the Azure Identity library.
An Azure Communication Services resource.

Register the Event Grid resource provider

This article describes how to register the Event Grid resource provider. If you used Event Grid before in the same subscription, skip to the next section.

In the Azure portal, do the following steps:

On the left menu, select Subscriptions.
Select the Subscription you want to use for Event Grid from the subscription list.
On the Subscription page, select Resource providers under Settings on the left menu.
Search for Microsoft.EventGrid, and confirm that the Status is Not Registered.
Select Microsoft.EventGrid in the provider list.
Select Register on the command bar.
Refresh to make sure the status of Microsoft.EventGrid is changed to Registered.

Install the SDK

First, install the Microsoft Azure Event Grid Management library for .NET with NuGet:

dotnet add package Azure.ResourceManager.EventGrid;

Include the Event Grid Management SDK in your C# project:

using Microsoft.Azure.Management.EventGrid;
using Microsoft.Azure.Management.EventGrid.Models;

Authenticate with Azure Identity library

Prerequisites

Create a Microsoft Entra application and Service Principal and set up a client secret or trusted certificate issued by certificate authority. Follow the instructions at Register a Microsoft Entra app and create a service principal.
Store the secret or the certificate in the Azure Keyvault.
Give contributor or owner access to the subscription to that application following the instructions at Grant a user access to Azure resources using the Azure portal.
Read more about Authorizing access to Event Grid resources.

The Azure Identity library provides Microsoft Entra ID (Formerly Azure Active Directory) token authentication support across the Azure SDK. It provides a set of TokenCredential implementations, which you can use to construct Azure SDK clients that support Microsoft Entra token authentication. For more information, see Azure Identity client library for .NET.

Include the Azure Identity client library for .NET with NuGet.

dotnet add package Azure.Identity;
dotnet add package Azure.Security.KeyVault.Secrets

Include the Azure Identity library in your C# project.

using Microsoft.Azure.Identity;
using Azure.Security.KeyVault.Secrets

You can either pass the secret credentials or certificate credentials to get access token, based on how your Service Principal is configured.

Get access token using secret credential

To get the secret credentials, you need to read it from the Keyvault you created in Prerequisite 2 using SecretClient.

// Authenticate the Keyvault client with DefaultAzureCredential and get the secret.
SecretClient secretClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
string clientSecret = await secretClient.GetSecretAsync(secretName).Value;

// Get access token using secret credentials
string[] scopes = { "https://management.azure.com/.default" };
var application = ConfidentialClientApplicationBuilder
                    .Create('your-servicePrincipal-appId')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId('your-tenant_id')
                    .WithClientSecret(clientSecret)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .ExecuteAsync();

Get access token using certificate credential.

To get the certificate credentials, you need to read it from the Keyvault you created in Prerequisite 2 using CertificateClient.

Read more about the Microsoft Entra application configuration authority in Application configuration options.

// Authenticate the certificate client with DefaultAzureCredential and get the certificate.
CertificateClient certificateClient = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());
X509Certificat2 cert = await certificateClient.DownloadCertificateAsync(certificateName);

// Get access token using certificate credentials
string[] scopes = { "https://management.azure.com/.default" };
string authority = "https://login.microsoftonline.com/<tenant>/";
var application = ConfidentialClientApplicationBuilder
                    .Create('<servicePrincipal-appId>')
                    .WithAuthority(authorityUri: new Uri(authority), validateAuthority: true)
                    .WithTenantId("<tenantId>")
                    .WithCertificate(cert)
                    .Build();

var token = await application
                .AcquireTokenForClient(scopes)
                .WithSendX5C(true)
                .ExecuteAsync();

Authenticate EventGridManagementClient with access token using secret or certificate credentials.

// Authenticate EventGridManagementClient with Microsoft Entra ID access token credential
eventGridClient = new EventGridManagementClient(new Uri("https://management.azure.com/"),
    new TokenCredentials(token.AccessToken));

eventGridClient.SubscriptionId = 'your_subscripiton_id';

Create Event Subscription

This code sample shows how to create the event subscription for the webhook subscriber endpoint.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] includedEventTypes = new string[]{ "Microsoft.Communication.SMSReceived", 
                                            "Microsoft.Communication.SMSDeliveryReportReceived"
                                            };

EventSubscription eventSubscription = new EventSubscription(
    name: "<eventSubscriptionName>",
    eventDeliverySchema: "EventGridSchema",
    filter: new EventSubscriptionFilter(
    includedEventTypes: includedEventTypes),
    destination: new WebHookEventSubscriptionDestination(webhookUri));

await eventGridClient.EventSubscriptions.CreateOrUpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionInfo: eventSubscription);

Update event subscription

This code sample shows how to update the event subscription to add more events that you want to receive on the webhook subscriber endpoint.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";
string[] additionalEventTypes = new string[]{ 
                                            "Microsoft.Communication.ChatMessageReceived"
                                        };

await eventGridClient.EventSubscriptions.UpdateAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>",
    eventSubscriptionUpdateParameters: new EventSubscriptionUpdateParameters(
            filter: new EventSubscriptionFilter(includedEventTypes: additionalEventTypes)));

Delete event Subscription

This code sample shows how to delete the event subscription for the webhook subscriber endpoint.

string webhookUri = $"<webhookUri>";
string resourceId="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>";

await eventGridClient.EventSubscriptions.DeleteAsync(
    scope: resourceId,
    eventSubscriptionName: "<eventSubscriptionName>");

Prerequisites

An Azure account with an active subscription. Create an account for free.
Install the Azure Az PowerShell Module.
An Azure Communication Services resource.
Create a Webhook to receive events. See Webhook Event Delivery.

Register the Event Grid resource provider

This article describes how to register the Event Grid Resource Provider. If you used Event Grid before in the same subscription, skip to the next section.

Run the following command:

Register-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

It may take a moment for the registration to finish. To check the status, run:

Get-AzResourceProvider -ProviderNamespace Microsoft.EventGrid

When RegistrationStatus is Registered, you're ready to continue.

Create event subscription

First, install the Azure Communication Services module Az.EventGrid using the following command.

PS C:\> Install-Module Az.EventGrid

Sign in to your Azure subscription with the Connect-AzAccount command and follow the on-screen directions.
```
Connect-AzAccount
```
If your identity is associated with more than one subscription, then set your active subscription to subscription of the Web PubSub resource that you want to move.
```
$context = Get-AzSubscription -SubscriptionId <subscription-id>
Set-AzContext $context
```

To create an event subscription using the Azure PowerShell, use the New-AzEventGridSubscription command.

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived"
New-AzEventGridSubscription 
    -EndpointType webhook
    -Endpoint https://azureeventgridviewer.azurewebsites.net/api/updates
    -EventSubscriptionName EventsWebhookSubscription 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

For a list of Communication Services events, see Communication Services Events.

List event subscriptions

To list all the existing event subscriptions set up for an Azure Communication Services resource using the Azure PowerShell, use the Get-AzEventGridSubscription command.

Get-AzEventGridSubscription 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>"

Update event subscription

To update an existing event subscription using the Azure PowerShell, use the Update-AzEventGridSubscription command.

$includedEventTypes = "Microsoft.Communication.SMSReceived", "Microsoft.Communication.SMSDeliveryReportReceived", "Microsoft.Communication.ChatMessageReceived"
Update-AzEventGridSubscription 
    -EventSubscriptionName ES2 
    -IncludedEventType $includedEventTypes
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" 
    -Endpoint https://azureeventgridviewer2.azurewebsites.net/api/updates
    -SubjectEndsWith "phoneNumber"

Delete event subscription

To delete an existing event subscription using the Azure PowerShell, use the Remove-AzEventGridSubscription command.

Get-AzResource 
    -ResourceId "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Communication/CommunicationServices/<acsResourceName>" | Remove-AzEventGridSubscription -EventSubscriptionName ES2

Next steps

For information on other commands, see Az.EventGrid PowerShell Module.

Share via

Prerequisites

Register the Event Grid resource provider

Create event subscription

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Install the SDK

Authenticate with Azure Identity library

Prerequisites

Create Event Subscription

Update event subscription

Delete event Subscription

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Feedback

Additional resources

Share via

Quickstart: Subscribe to Azure Communication Services events

Prerequisites

Register the Event Grid resource provider

Create event subscription

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Prerequisites

Register the Event Grid resource provider

Install the SDK

Authenticate with Azure Identity library

Prerequisites

Create Event Subscription

Update event subscription

Delete event Subscription

Prerequisites

Register the Event Grid resource provider

Create event subscription

List event subscriptions

Update event subscription

Delete event subscription

Next steps

Feedback

Additional resources