{"id":1923,"library":"azure-eventgrid","title":"Azure Event Grid Client Library","description":"The Azure Event Grid client library for Python is used to publish events to Event Grid topics and to deserialize events received from Event Grid. It supports both the CloudEvents 1.0 schema and the Event Grid schema. The current version is 4.22.0, with frequent updates aligning with broader Azure SDK releases.","status":"active","version":"4.22.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/eventgrid","tags":["Azure","Event Grid","Messaging","Cloud Events","Serverless","Webhooks"],"install":[{"cmd":"pip install azure-eventgrid","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"EventGridClient was used in older V1 versions; EventGridPublisherClient is for current V4+.","wrong":"from azure.eventgrid import EventGridClient","symbol":"EventGridPublisherClient","correct":"from azure.eventgrid import EventGridPublisherClient"},{"symbol":"EventGridDeserializer","correct":"from azure.eventgrid import EventGridDeserializer"},{"note":"In V4+, EventGridEvent and CloudEvent are directly under azure.eventgrid, not a 'models' submodule.","wrong":"from azure.eventgrid.models import CloudEvent","symbol":"CloudEvent","correct":"from azure.eventgrid import CloudEvent"},{"note":"In V4+, EventGridEvent and CloudEvent are directly under azure.eventgrid, not a 'models' submodule.","wrong":"from azure.eventgrid.models import EventGridEvent","symbol":"EventGridEvent","correct":"from azure.eventgrid import EventGridEvent"},{"symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"}],"quickstart":{"code":"import os\nimport json\nfrom azure.eventgrid import EventGridPublisherClient, EventGridEvent, CloudEvent, EventGridDeserializer\nfrom azure.core.credentials import AzureKeyCredential\n\n# Set your Event Grid endpoint and access key from environment variables\nEVENT_GRID_ENDPOINT = os.environ.get(\"EVENT_GRID_ENDPOINT\", \"\")\nEVENT_GRID_KEY = os.environ.get(\"EVENT_GRID_KEY\", \"\")\n\nif not EVENT_GRID_ENDPOINT or not EVENT_GRID_KEY:\n    print(\"Please set the environment variables EVENT_GRID_ENDPOINT and EVENT_GRID_KEY.\")\n    exit(1)\n\ncredential = AzureKeyCredential(EVENT_GRID_KEY)\nclient = EventGridPublisherClient(EVENT_GRID_ENDPOINT, credential)\n\n# --- Publish a CloudEvent ---\ncloud_event = CloudEvent(\n    source=\"https://example.com/myapp\",\n    type=\"Contoso.Items.ItemReceived\",\n    data={\"itemSku\": \"CONTOSO-ITEM-0001\", \"itemCount\": 1},\n    subject=\"MySubject\",\n    # Additional CloudEvent attributes can be passed as keyword arguments\n)\nclient.send([cloud_event])\nprint(\"Published a CloudEvent successfully.\")\n\n# --- Publish an EventGridEvent ---\nevent_grid_event = EventGridEvent(\n    subject=\"Contoso/Items/ItemReceived\",\n    data={\"itemSku\": \"CONTOSO-ITEM-0002\", \"itemCount\": 1},\n    event_type=\"Contoso.Items.ItemReceived\",\n    data_version=\"1.0\",\n)\nclient.send([event_grid_event])\nprint(\"Published an EventGridEvent successfully.\")\n\n# --- Deserialize an incoming event (e.g., from a webhook payload) ---\nsimulated_webhook_payload = json.dumps([\n    {\n        \"id\": \"test-event-id-1\",\n        \"source\": \"/azure/events/test\",\n        \"data\": {\"message\": \"Hello CloudEvent!\"},\n        \"type\": \"test.event\",\n        \"time\": \"2023-10-27T10:00:00Z\",\n        \"specversion\": \"1.0\"\n    },\n    {\n        \"id\": \"test-event-id-2\",\n        \"topic\": \"/subscriptions/xxx/resourceGroups/yyy/providers/Microsoft.EventGrid/topics/mytesttopic\",\n        \"subject\": \"TestSubject\",\n        \"data\": {\"message\": \"Hello EventGridEvent!\"},\n        \"eventTime\": \"2023-10-27T10:05:00Z\",\n        \"eventType\": \"Microsoft.Storage.BlobCreated\",\n        \"dataVersion\": \"1.0\",\n        \"metadataVersion\": \"1\",\n        \"blobType\": \"BlockBlob\"\n    }\n])\n\ndeserializer = EventGridDeserializer()\ndeserialized_events = deserializer.deserialize_events(simulated_webhook_payload)\n\nprint(\"\\nDeserialized events from simulated webhook payload:\")\nfor event in deserialized_events:\n    if isinstance(event, CloudEvent):\n        print(f\"  CloudEvent - ID: {event.id}, Type: {event.type}, Data: {event.data}\")\n    elif isinstance(event, EventGridEvent):\n        print(f\"  EventGridEvent - ID: {event.id}, Type: {event.event_type}, Subject: {event.subject}\")","lang":"python","description":"This quickstart demonstrates how to publish both CloudEvents and Event Grid Schema events to an Event Grid topic using `EventGridPublisherClient` and then how to deserialize incoming event payloads using `EventGridDeserializer`. Ensure `EVENT_GRID_ENDPOINT` and `EVENT_GRID_KEY` environment variables are set."},"warnings":[{"fix":"Upgrade to `azure-eventgrid>=4.0.0` and update your code. Use `EventGridPublisherClient` for publishing and import `EventGridEvent` or `CloudEvent` directly from `azure.eventgrid`.","message":"The `azure-eventgrid` library underwent significant API changes between its V1 (1.x.x) and V4 (4.x.x) versions. Classes like `EventGridClient` for publishing and the `azure.eventgrid.models` submodule for event types (`EventGridEvent`, `CloudEvent`) were replaced.","severity":"breaking","affected_versions":"<4.0.0"},{"fix":"Carefully review your Event Grid topic's schema configuration and use the appropriate `CloudEvent` or `EventGridEvent` class. When publishing, the client will serialize events according to the object type provided. When deserializing, `EventGridDeserializer` can handle both.","message":"Event Grid supports two main event schemas: CloudEvents 1.0 and the Event Grid schema. You must correctly choose and construct the event type (`CloudEvent` or `EventGridEvent`) corresponding to the schema your Event Grid topic is configured to accept, or that you expect to receive. Mismatched schemas can lead to events being dropped or malformed.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure you import from `azure.eventgrid` for data plane operations (publishing/deserializing events) and `azure.mgmt.eventgrid` for resource management operations.","message":"There are two distinct Python libraries: `azure-eventgrid` (this data plane client) and `azure-mgmt-eventgrid` (the management plane client). `azure-eventgrid` is for sending/receiving actual events, while `azure-mgmt-eventgrid` is for creating, updating, and deleting Event Grid topics, domains, and subscriptions. Using the wrong library for your task will result in `AttributeError` or unexpected behavior.","severity":"gotcha","affected_versions":"All"},{"fix":"Implement logic in your webhook endpoint to detect 'Microsoft.EventGrid.SubscriptionValidationEvent' and return a JSON response like `{'validationResponse': event.data['validationCode']}`.","message":"When receiving events via HTTP (e.g., a webhook), Event Grid sends a 'webhook validation' event. Your application must respond to this validation event within 30 seconds by returning the 'validationCode' in the response body. Failing to do so will prevent the subscription from becoming active.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}