How to have event grid trigger OAuth Secured Webhook

Hi Duncan, Brandon,

By default, Event Grid webhooks support only SAS or client-secret/​certificate based OAuth authentication. The documentation for using a managed identity as the credential source for webhooks is sparse. You must explicitly configure:

• A system-assigned identity on the Event Grid subscription resource.
• The subscription’s destination.authentication block to use ManagedIdentity
• The correct App-ID URI (audience) for your webhook so that tokens are issued for the right resource.

Steps to Follow

1. In the Azure Portal navigate to your Event Grid Topic (or Domain) → Event Subscriptions → + Create.
2. Under Basics, supply Subscription name, Event Schema, etc.
3. Under Destination, choose Web Hook.
4. Click Authentication → select Managed identity (Preview).
   • For Identity type, choose System assigned.
   • For Azure AD Audience, enter the App-ID URI of your webhook API (for example api://contoso-webhook).
5. Complete any Filters if needed, then Review + create.

Diagnosis and Troubleshooting

• If you see HTTP 401 on your webhook side
  • Confirm the audience in your subscription matches the App-ID URI your API trusts.
  • In Azure AD App Registrations for your webhook, under Expose an API, ensure that the scope/audience equals your audience.
  • Check the subscription’s identity principalId: az eventgrid event-subscription show --name myEgSub --source-resource-id <resourceId> --query identity.principalId -o tsv
  • In your API’s code or gateway, log the incoming Authorization header and validate the token using Microsoft.Identity.Web or your JWT library.
• If the CLI command fails with "invalid parameter"
  • Update Azure CLI to latest version and az extension update --name eventgrid.
  • Ensure your subscription uses API version 2021-06-01 preview or later.

Points to consider

• Managed Identity support for Event Grid webhooks requires API version ≥ 2021-06-01-preview in CLI or Portal.
• For multi-tenant or cross-tenant scenarios use user-assigned identities and specify resourceId of the user-assigned identity.
• Best Practice: Expose minimal scopes and use least-privilege when registering and protecting your webhook API (e.g., single scope access_eventgrid).
• Alternative: Client Certificate authentication if your environment does not yet support managed identity.
• Performance: Token caching by the Event Grid service reduces token requests — minimal latency impact.

Reference: https://free.blessedness.top/en-us/azure/event-grid/managed-service-identity