Share via

System Topic Event Subscriptions - Create Or Update

  • Reference
Service:
Event Grid
API Version:
2022-06-15

Create or update an event subscription for a system topic.
Asynchronously creates or updates an event subscription with the specified parameters. Existing event subscriptions will be updated with this API.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/systemTopics/{systemTopicName}/eventSubscriptions/{eventSubscriptionName}?api-version=2022-06-15

URI Parameters

Name In Required Type Description
eventSubscriptionName
 path True

string

Name of the event subscription to be created. Event subscription names must be between 3 and 100 characters in length and use alphanumeric letters only.
resourceGroupName
 path True

string

The name of the resource group within the user's subscription.
subscriptionId
 path True

string

Subscription credentials that uniquely identify a Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.
systemTopicName
 path True

string

Name of the system topic.
api-version
 query True

string

Version of the API to be used with the client request.

Request Body

Name Type Description
properties.deadLetterDestination DeadLetterDestination:

StorageBlobDeadLetterDestination

The dead letter destination of the event subscription. Any event that cannot be delivered to its' destination is sent to the dead letter destination. Uses Azure Event Grid's identity to acquire the authentication tokens being used during delivery / dead-lettering.
properties.deadLetterWithResourceIdentity

DeadLetterWithResourceIdentity

The dead letter destination of the event subscription. Any event that cannot be delivered to its' destination is sent to the dead letter destination. Uses the managed identity setup on the parent resource (namely, topic or domain) to acquire the authentication tokens being used during delivery / dead-lettering.
properties.deliveryWithResourceIdentity

DeliveryWithResourceIdentity

Information about the destination where events have to be delivered for the event subscription. Uses the managed identity setup on the parent resource (namely, topic or domain) to acquire the authentication tokens being used during delivery / dead-lettering.
properties.destination EventSubscriptionDestination:

Information about the destination where events have to be delivered for the event subscription. Uses Azure Event Grid's identity to acquire the authentication tokens being used during delivery / dead-lettering.
properties.eventDeliverySchema

EventDeliverySchema

The event delivery schema for the event subscription.
properties.expirationTimeUtc

string

Expiration time of the event subscription.
properties.filter

EventSubscriptionFilter

Information about the filter for the event subscription.
properties.labels

string[]

List of user defined labels.
properties.retryPolicy

RetryPolicy

The retry policy for events. This can be used to configure maximum number of delivery attempts and time to live for events.

Responses

Name Type Description
201 Created

EventSubscription

Created
Other Status Codes

*** Error Responses: ***

  • 400 Bad Request.

  • 500 Internal Server Error.

Examples

SystemTopicEventSubscriptions_CreateOrUpdate

Sample request

PUT https://management.azure.com/subscriptions/5b4b650e-28b9-4790-b3ab-ddbd88d727c4/resourceGroups/examplerg/providers/Microsoft.EventGrid/systemTopics/exampleSystemTopic1/eventSubscriptions/exampleEventSubscriptionName1?api-version=2022-06-15

{
  "properties": {
    "destination": {
      "endpointType": "WebHook",
      "properties": {
        "endpointUrl": "https://requestb.in/15ksip71"
      }
    },
    "filter": {
      "isSubjectCaseSensitive": false,
      "subjectBeginsWith": "ExamplePrefix",
      "subjectEndsWith": "ExampleSuffix"
    }
  }
}

Sample response

Status code:
201 
{
  "properties": {
    "destination": {
      "properties": {
        "endpointBaseUrl": "https://requestb.in/15ksip71"
      },
      "endpointType": "WebHook"
    },
    "filter": {
      "isSubjectCaseSensitive": false,
      "subjectBeginsWith": "ExamplePrefix",
      "subjectEndsWith": "ExampleSuffix"
    },
    "labels": null,
    "eventDeliverySchema": "EventGridSchema",
    "retryPolicy": {
      "maxDeliveryAttempts": 30,
      "eventTimeToLiveInMinutes": 1440
    },
    "provisioningState": "Succeeded",
    "topic": "/subscriptions/5b4b650e-28b9-4790-b3ab-ddbd88d727c4/resourceGroups/examplerg/providers/Microsoft.EventGrid/systemTopics/exampleSystemTopic1"
  },
  "id": "/subscriptions/5b4b650e-28b9-4790-b3ab-ddbd88d727c4/resourceGroups/examplerg/providers/Microsoft.EventGrid/systemTopics/exampleSystemTopic1/eventSubscriptions/exampleEventSubscriptionName1",
  "name": "exampleEventSubscriptionName1",
  "type": "Microsoft.EventGrid/systemTopics/eventSubscriptions"
}

Definitions

Name Description
AzureFunctionEventSubscriptionDestination

Information about the azure function destination for an event subscription.
BoolEqualsAdvancedFilter

BoolEquals Advanced Filter.
createdByType

The type of identity that created the resource.
DeadLetterWithResourceIdentity

Information about the deadletter destination with resource identity.
DeliveryWithResourceIdentity

Information about the delivery for an event subscription with resource identity.
DynamicDeliveryAttributeMapping

Dynamic delivery attribute mapping details.
EventDeliverySchema

The event delivery schema for the event subscription.
EventHubEventSubscriptionDestination

Information about the event hub destination for an event subscription.
EventSubscription

Event Subscription
EventSubscriptionFilter

Filter for the Event Subscription.
EventSubscriptionIdentity

The identity information with the event subscription.
EventSubscriptionIdentityType

The type of managed identity used. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user-assigned identities. The type 'None' will remove any identity.
EventSubscriptionProvisioningState

Provisioning state of the event subscription.
HybridConnectionEventSubscriptionDestination

Information about the HybridConnection destination for an event subscription.
IsNotNullAdvancedFilter

IsNotNull Advanced Filter.
IsNullOrUndefinedAdvancedFilter

IsNullOrUndefined Advanced Filter.
NumberGreaterThanAdvancedFilter

NumberGreaterThan Advanced Filter.
NumberGreaterThanOrEqualsAdvancedFilter

NumberGreaterThanOrEquals Advanced Filter.
NumberInAdvancedFilter

NumberIn Advanced Filter.
NumberInRangeAdvancedFilter

NumberInRange Advanced Filter.
NumberLessThanAdvancedFilter

NumberLessThan Advanced Filter.
NumberLessThanOrEqualsAdvancedFilter

NumberLessThanOrEquals Advanced Filter.
NumberNotInAdvancedFilter

NumberNotIn Advanced Filter.
NumberNotInRangeAdvancedFilter

NumberNotInRange Advanced Filter.
RetryPolicy

Information about the retry policy for an event subscription.
ServiceBusQueueEventSubscriptionDestination

Information about the service bus destination for an event subscription.
ServiceBusTopicEventSubscriptionDestination

Information about the service bus topic destination for an event subscription.
StaticDeliveryAttributeMapping

Static delivery attribute mapping details.
StorageBlobDeadLetterDestination

Information about the storage blob based dead letter destination.
StorageQueueEventSubscriptionDestination

Information about the storage queue destination for an event subscription.
StringBeginsWithAdvancedFilter

StringBeginsWith Advanced Filter.
StringContainsAdvancedFilter

StringContains Advanced Filter.
StringEndsWithAdvancedFilter

StringEndsWith Advanced Filter.
StringInAdvancedFilter

StringIn Advanced Filter.
StringNotBeginsWithAdvancedFilter

StringNotBeginsWith Advanced Filter.
StringNotContainsAdvancedFilter

StringNotContains Advanced Filter.
StringNotEndsWithAdvancedFilter

StringNotEndsWith Advanced Filter.
StringNotInAdvancedFilter

StringNotIn Advanced Filter.
systemData

Metadata pertaining to creation and last modification of the resource.
WebHookEventSubscriptionDestination

Information about the webhook destination for an event subscription.

AzureFunctionEventSubscriptionDestination

Information about the azure function destination for an event subscription.

Name Type Default value Description
endpointType string:

AzureFunction

Type of the endpoint for the event subscription destination.
properties.deliveryAttributeMappings DeliveryAttributeMapping[]:

Delivery attribute details.
properties.maxEventsPerBatch

integer

1

Maximum number of events per batch.
properties.preferredBatchSizeInKilobytes

integer

64

Preferred batch size in Kilobytes.
properties.resourceId

string

The Azure Resource Id that represents the endpoint of the Azure Function destination of an event subscription.

BoolEqualsAdvancedFilter

BoolEquals Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

BoolEquals

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
value

boolean

The boolean filter value.

createdByType

The type of identity that created the resource.

Name Type Description
Application

string

Key

string

ManagedIdentity

string

User

string

DeadLetterWithResourceIdentity

Information about the deadletter destination with resource identity.

Name Type Description
deadLetterDestination DeadLetterDestination:

StorageBlobDeadLetterDestination

Information about the destination where events have to be delivered for the event subscription. Uses the managed identity setup on the parent resource (namely, topic or domain) to acquire the authentication tokens being used during delivery / dead-lettering.
identity

EventSubscriptionIdentity

The identity to use when dead-lettering events.

DeliveryWithResourceIdentity

Information about the delivery for an event subscription with resource identity.

Name Type Description
destination EventSubscriptionDestination:

Information about the destination where events have to be delivered for the event subscription. Uses Azure Event Grid's identity to acquire the authentication tokens being used during delivery / dead-lettering.
identity

EventSubscriptionIdentity

The identity to use when delivering events.

DynamicDeliveryAttributeMapping

Dynamic delivery attribute mapping details.

Name Type Description
name

string

Name of the delivery attribute or header.
properties.sourceField

string

JSON path in the event which contains attribute value.
type string:

Dynamic

Type of the delivery attribute or header name.

EventDeliverySchema

The event delivery schema for the event subscription.

Name Type Description
CloudEventSchemaV1_0

string

CustomInputSchema

string

EventGridSchema

string

EventHubEventSubscriptionDestination

Information about the event hub destination for an event subscription.

Name Type Description
endpointType string:

EventHub

Type of the endpoint for the event subscription destination.
properties.deliveryAttributeMappings DeliveryAttributeMapping[]:

Delivery attribute details.
properties.resourceId

string

The Azure Resource Id that represents the endpoint of an Event Hub destination of an event subscription.

EventSubscription

Event Subscription

Name Type Default value Description
id

string

Fully qualified identifier of the resource.
name

string

Name of the resource.
properties.deadLetterDestination DeadLetterDestination:

StorageBlobDeadLetterDestination

The dead letter destination of the event subscription. Any event that cannot be delivered to its' destination is sent to the dead letter destination. Uses Azure Event Grid's identity to acquire the authentication tokens being used during delivery / dead-lettering.
properties.deadLetterWithResourceIdentity

DeadLetterWithResourceIdentity

The dead letter destination of the event subscription. Any event that cannot be delivered to its' destination is sent to the dead letter destination. Uses the managed identity setup on the parent resource (namely, topic or domain) to acquire the authentication tokens being used during delivery / dead-lettering.
properties.deliveryWithResourceIdentity

DeliveryWithResourceIdentity

Information about the destination where events have to be delivered for the event subscription. Uses the managed identity setup on the parent resource (namely, topic or domain) to acquire the authentication tokens being used during delivery / dead-lettering.
properties.destination EventSubscriptionDestination:

Information about the destination where events have to be delivered for the event subscription. Uses Azure Event Grid's identity to acquire the authentication tokens being used during delivery / dead-lettering.
properties.eventDeliverySchema

EventDeliverySchema

EventGridSchema

The event delivery schema for the event subscription.
properties.expirationTimeUtc

string

Expiration time of the event subscription.
properties.filter

EventSubscriptionFilter

Information about the filter for the event subscription.
properties.labels

string[]

List of user defined labels.
properties.provisioningState

EventSubscriptionProvisioningState

Provisioning state of the event subscription.
properties.retryPolicy

RetryPolicy

The retry policy for events. This can be used to configure maximum number of delivery attempts and time to live for events.
properties.topic

string

Name of the topic of the event subscription.
systemData

systemData

The system metadata relating to Event Subscription resource.
type

string

Type of the resource.

EventSubscriptionFilter

Filter for the Event Subscription.

Name Type Default value Description
advancedFilters AdvancedFilter[]:

An array of advanced filters that are used for filtering event subscriptions.
enableAdvancedFilteringOnArrays

boolean

Allows advanced filters to be evaluated against an array of values instead of expecting a singular value.
includedEventTypes

string[]

A list of applicable event types that need to be part of the event subscription. If it is desired to subscribe to all default event types, set the IncludedEventTypes to null.
isSubjectCaseSensitive

boolean

False

Specifies if the SubjectBeginsWith and SubjectEndsWith properties of the filter should be compared in a case sensitive manner.
subjectBeginsWith

string

An optional string to filter events for an event subscription based on a resource path prefix. The format of this depends on the publisher of the events. Wildcard characters are not supported in this path.
subjectEndsWith

string

An optional string to filter events for an event subscription based on a resource path suffix. Wildcard characters are not supported in this path.

EventSubscriptionIdentity

The identity information with the event subscription.

Name Type Description
type

EventSubscriptionIdentityType

The type of managed identity used. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user-assigned identities. The type 'None' will remove any identity.
userAssignedIdentity

string

The user identity associated with the resource.

EventSubscriptionIdentityType

The type of managed identity used. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user-assigned identities. The type 'None' will remove any identity.

Name Type Description
SystemAssigned

string

UserAssigned

string

EventSubscriptionProvisioningState

Provisioning state of the event subscription.

Name Type Description
AwaitingManualAction

string

Canceled

string

Creating

string

Deleting

string

Failed

string

Succeeded

string

Updating

string

HybridConnectionEventSubscriptionDestination

Information about the HybridConnection destination for an event subscription.

Name Type Description
endpointType string:

HybridConnection

Type of the endpoint for the event subscription destination.
properties.deliveryAttributeMappings DeliveryAttributeMapping[]:

Delivery attribute details.
properties.resourceId

string

The Azure Resource ID of an hybrid connection that is the destination of an event subscription.

IsNotNullAdvancedFilter

IsNotNull Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

IsNotNull

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.

IsNullOrUndefinedAdvancedFilter

IsNullOrUndefined Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

IsNullOrUndefined

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.

NumberGreaterThanAdvancedFilter

NumberGreaterThan Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberGreaterThan

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
value

number

The filter value.

NumberGreaterThanOrEqualsAdvancedFilter

NumberGreaterThanOrEquals Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberGreaterThanOrEquals

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
value

number

The filter value.

NumberInAdvancedFilter

NumberIn Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberIn

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

number[]

The set of filter values.

NumberInRangeAdvancedFilter

NumberInRange Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberInRange

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

number[]

The set of filter values.

NumberLessThanAdvancedFilter

NumberLessThan Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberLessThan

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
value

number

The filter value.

NumberLessThanOrEqualsAdvancedFilter

NumberLessThanOrEquals Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberLessThanOrEquals

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
value

number

The filter value.

NumberNotInAdvancedFilter

NumberNotIn Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberNotIn

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

number[]

The set of filter values.

NumberNotInRangeAdvancedFilter

NumberNotInRange Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

NumberNotInRange

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

number[]

The set of filter values.

RetryPolicy

Information about the retry policy for an event subscription.

Name Type Default value Description
eventTimeToLiveInMinutes

integer

1440

Time To Live (in minutes) for events.
maxDeliveryAttempts

integer

30

Maximum number of delivery retry attempts for events.

ServiceBusQueueEventSubscriptionDestination

Information about the service bus destination for an event subscription.

Name Type Description
endpointType string:

ServiceBusQueue

Type of the endpoint for the event subscription destination.
properties.deliveryAttributeMappings DeliveryAttributeMapping[]:

Delivery attribute details.
properties.resourceId

string

The Azure Resource Id that represents the endpoint of the Service Bus destination of an event subscription.

ServiceBusTopicEventSubscriptionDestination

Information about the service bus topic destination for an event subscription.

Name Type Description
endpointType string:

ServiceBusTopic

Type of the endpoint for the event subscription destination.
properties.deliveryAttributeMappings DeliveryAttributeMapping[]:

Delivery attribute details.
properties.resourceId

string

The Azure Resource Id that represents the endpoint of the Service Bus Topic destination of an event subscription.

StaticDeliveryAttributeMapping

Static delivery attribute mapping details.

Name Type Default value Description
name

string

Name of the delivery attribute or header.
properties.isSecret

boolean

False

Boolean flag to tell if the attribute contains sensitive information .
properties.value

string

Value of the delivery attribute.
type string:

Static

Type of the delivery attribute or header name.

StorageBlobDeadLetterDestination

Information about the storage blob based dead letter destination.

Name Type Description
endpointType string:

StorageBlob

Type of the endpoint for the dead letter destination
properties.blobContainerName

string

The name of the Storage blob container that is the destination of the deadletter events
properties.resourceId

string

The Azure Resource ID of the storage account that is the destination of the deadletter events

StorageQueueEventSubscriptionDestination

Information about the storage queue destination for an event subscription.

Name Type Description
endpointType string:

StorageQueue

Type of the endpoint for the event subscription destination.
properties.queueMessageTimeToLiveInSeconds

integer

Storage queue message time to live in seconds.
properties.queueName

string

The name of the Storage queue under a storage account that is the destination of an event subscription.
properties.resourceId

string

The Azure Resource ID of the storage account that contains the queue that is the destination of an event subscription.

StringBeginsWithAdvancedFilter

StringBeginsWith Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringBeginsWith

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringContainsAdvancedFilter

StringContains Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringContains

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringEndsWithAdvancedFilter

StringEndsWith Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringEndsWith

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringInAdvancedFilter

StringIn Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringIn

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringNotBeginsWithAdvancedFilter

StringNotBeginsWith Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringNotBeginsWith

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringNotContainsAdvancedFilter

StringNotContains Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringNotContains

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringNotEndsWithAdvancedFilter

StringNotEndsWith Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringNotEndsWith

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

StringNotInAdvancedFilter

StringNotIn Advanced Filter.

Name Type Description
key

string

The field/property in the event based on which you want to filter.
operatorType string:

StringNotIn

The operator type used for filtering, e.g., NumberIn, StringContains, BoolEquals and others.
values

string[]

The set of filter values.

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string

The timestamp of resource creation (UTC).
createdBy

string

The identity that created the resource.
createdByType

createdByType

The type of identity that created the resource.
lastModifiedAt

string

The timestamp of resource last modification (UTC)
lastModifiedBy

string

The identity that last modified the resource.
lastModifiedByType

createdByType

The type of identity that last modified the resource.

WebHookEventSubscriptionDestination

Information about the webhook destination for an event subscription.

Name Type Default value Description
endpointType string:

WebHook

Type of the endpoint for the event subscription destination.
properties.azureActiveDirectoryApplicationIdOrUri

string

The Azure Active Directory Application ID or URI to get the access token that will be included as the bearer token in delivery requests.
properties.azureActiveDirectoryTenantId

string

The Azure Active Directory Tenant ID to get the access token that will be included as the bearer token in delivery requests.
properties.deliveryAttributeMappings DeliveryAttributeMapping[]:

Delivery attribute details.
properties.endpointBaseUrl

string

The base URL that represents the endpoint of the destination of an event subscription.
properties.endpointUrl

string

The URL that represents the endpoint of the destination of an event subscription.
properties.maxEventsPerBatch

integer

1

Maximum number of events per batch.
properties.preferredBatchSizeInKilobytes

integer

64

Preferred batch size in Kilobytes.