azure-event-grid-webhooks
Receive and validate Azure Event Grid webhook deliveries. Use when setting up an Event Grid WebHook event handler, implementing the Microsoft.EventGrid.SubscriptionValidationEvent handshake (echo data.validationCode as validationResponse with HTTP 200), implementing the CloudEvents v1.0 HTTP OPTIONS abuse-protection preflight (WebHook-Request-Origin / WebHook-Allowed-Origin), checking the aeg-subscription-name / aeg-event-type / aeg-delivery-count headers, authenticating deliveries with a static delivery-property header or a Microsoft Entra ID bearer token, parsing Event Grid schema arrays vs CloudEvents objects, or handling events like Microsoft.Storage.BlobCreated. Event Grid does NOT sign the request body — there is no HMAC signature.
hookdeck · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add hookdeck/webhook-skills --skill azure-event-grid-webhooks技能说明
name: azure-event-grid-webhooks description: > Receive and validate Azure Event Grid webhook deliveries. Use when setting up an Event Grid WebHook event handler, implementing the Microsoft.EventGrid.SubscriptionValidationEvent handshake (echo data.validationCode as validationResponse with HTTP 200), implementing the CloudEvents v1.0 HTTP OPTIONS abuse-protection preflight (WebHook-Request-Origin / WebHook-Allowed-Origin), checking the aeg-subscription-name / aeg-event-type / aeg-delivery-count headers, authenticating deliveries with a static delivery-property header or a Microsoft Entra ID bearer token, parsing Event Grid schema arrays vs CloudEvents objects, or handling events like Microsoft.Storage.BlobCreated. Event Grid does NOT sign the request body — there is no HMAC signature. license: MIT metadata: author: hookdeck version: "0.1.0" repository: https://github.com/hookdeck/webhook-skills
Azure Event Grid Webhooks
When to Use This Skill
- How do I receive Azure Event Grid events at an HTTP endpoint?
- How do I verify an Azure Event Grid webhook? Where is the signature header?
- How do I handle
Microsoft.EventGrid.SubscriptionValidationEvent? - Why is my Event Grid event subscription stuck in
AwaitingManualActionorFailed? - What is
WebHook-Request-Origin/WebHook-Allowed-Originand why is Event Grid sending me an HTTP OPTIONS request? - How do I authenticate Event Grid deliveries with a custom header, a query-parameter secret, or Microsoft Entra ID?
- How do I parse
Microsoft.Storage.BlobCreatedfrom an Event Grid array vs a CloudEvents object?
There Is No Signature — Read This First
Event Grid is a managed pub/sub broker, not a single-vendor webhook signer.
- Event Grid does not sign the request body. There is no
X-Signature, no HMAC, no shared signing secret, no timestamp+signature pair, no asymmetric signature. Do not write acrypto.createHmac/hmac.newverifier for Event Grid — there is nothing to verify against. - Security comes from two other things, and a production handler needs both:
| Layer | What it proves | Mechanism |
|---|---|---|
| Handshake (subscription time) | You own the endpoint and expected this subscription | SubscriptionValidationEvent echo, or the CloudEvents OPTIONS preflight |
| Channel auth (every delivery) | The caller is who you configured | A static delivery-property header you choose, a client secret in a query parameter, or a Microsoft Entra ID bearer token |
- Because nothing is signed, there is no raw-body requirement. Parsing JSON before authenticating is safe here in a way it never is for Stripe or Shopify.
If you are looking at Hookdeck's
AZURE_EVENT_GRIDsource config and see HMAC / Basic Auth / API Key options: those configure a header you attach via Event Grid delivery properties. Azure computes no HMAC over the payload.
Two Handshakes — Which One Fires Depends on the Delivery Schema
| Event subscription's delivery schema | Handshake | Method |
|---|---|---|
Event Grid schema (eventgridschema) | Microsoft.EventGrid.SubscriptionValidationEvent — echo the code | POST |
CloudEvents v1.0 schema (cloudeventschemav1_0) | CloudEvents abuse protection preflight | OPTIONS |
Verbatim from the docs: "When you use the CloudEvents schema for output, Event Grid uses the CloudEvents v1.0 abuse protection in place of the Event Grid validation event mechanism." Implement both — one handler, two paths.
Validation Handshake (core)
Event Grid POSTs a JSON array containing only the validation event, with
header aeg-event-type: SubscriptionValidation. Gate on
aeg-subscription-name first: withholding the echo is how you deliberately
fail validation for a subscription you did not create.
const VALIDATION_EVENT = 'Microsoft.EventGrid.SubscriptionValidationEvent';
// Event Grid schema arrives as an ARRAY; CloudEvents as a single OBJECT.
const events = Array.isArray(body) ? body : [body];
const validation = events.find((e) => e && e.eventType === VALIDATION_EVENT);
if (validation) {
const subscription = String(req.get('aeg-subscription-name') || '').toLowerCase();
// An attacker who learns your URL can point their own subscription at it.
if (!EXPECTED_SUBSCRIPTIONS.includes(subscription)) {
return res.sendStatus(403); // No 200, no echo => validation fails. Intended.
}
// MUST be 200 — "HTTP 202 Accepted isn't recognized as a valid Event Grid
// subscription validation response" — and must complete within 30 seconds.
return res.status(200).json({ validationResponse: validation.data.validationCode });
}
The documented response field is camelCase validationResponse. Microsoft's own
C#/JS samples on the receive-events page emit PascalCase ValidationResponse;
the docs do not state whether matching is case-sensitive, so use the documented
camelCase form.
CloudEvents Abuse-Protection Preflight (core)
// OPTIONS on the exact endpoint URI being registered. Consent is signalled by
// the HEADERS, not the status code.
app.options('/webhooks/azure-event-grid', (req, res) => {
const origin = req.get('WebHook-Request-Origin'); // e.g. eventemitter.example.com
if (!origin || !isAllowedOrigin(origin)) return res.sendStatus(403); // withhold consent
res.set('WebHook-Allowed-Origin', origin); // or '*'
res.set('WebHook-Allowed-Rate', '120'); // requests per minute, or '*'
res.set('Allow', 'POST, OPTIONS');
res.sendStatus(200);
});
This handshake "doesn't aim to establish an authentication or authorization context" — it only proves the endpoint expects traffic. Channel auth still matters.
Channel Authentication (core)
The practical shared-secret path is a static delivery property: a custom header you configure on the event
阅读完整来源 ↗