用途:用于搭建 Cisco Meraki Dashboard 的 Webhook(HTTP 服务器)处理程序,验证 sharedSecret,并处理各类告警事件。
主要能力与要点:Meraki 不使用 HMAC 签名头,也不遵循 Standard Webhooks 规范,请求体内含明文 sharedSecret 字段,需与 Dashboard(Network-wide → Alerts → Webhooks / HTTP servers)中配置的密钥做定时安全比较。密钥为可选项且未加密传输,真正的传输保护依赖 TLS(CA 可信证书,不支持自签名)。需显式区分是否配置密钥:未配置时两侧都转为空字符串、任何请求都通过且无警告,属静默 fail-open;未设置表示仅依赖 TLS(接受但需警告),已设置则载荷必须携带匹配的 sharedSecret。处理时应先验证、再解析、最后幂等处理。
告警类型:载荷含 alertType(人类可读标签)与 alertTypeId(稳定机器标识),应基于 alertTypeId 分发。常见类型包括 motion_alert、settings_changed、sensor_alert、stopped_reporting。实时列表可通过 GET /organizations/{organizationId}/webhooks/alertTypes 获取。
载荷结构:默认非模板载荷含 version、sharedSecret、sentAt、occurredAt、organizationId、organizationName、organizationUrl、networkId、networkName、networkUrl、deviceSerial、alertId、alertType、alertTypeId、alertLevel、alertData。自定义模板使用 Liquid,可能改变头部与主体结构,包括移动或重命名 sharedSecret,启用后不能假定默认结构。
使用方式:设置环境变量 MERAKI_WEBHOOK_SECRET。本地开发可用 npx hookdeck-cli listen 3000 meraki --path /webhooks/meraki 启动隧道,并在 Dashboard 用 Send test 发送样例。示例处理程序见 examples/express/、examples/nextjs/、examples/fastapi/。
限制:Meraki 在 24 小时内失败尝试超过 100 次会自动禁用接收端,需配合重试与幂等逻辑。