# Cisco Meraki Webhooks

## When to Use This Skill

* Setting up Cisco Meraki Dashboard webhook (HTTP server) handlers
* How do I verify Meraki webhooks? / validating the Meraki `sharedSecret`
* Understanding Meraki alert types and payload structure
* Handling `motion_alert`, `settings_changed`, `sensor_alert`, or `stopped_reporting` alerts
* Why is my Meraki webhook `sharedSecret` check failing?

## Verification (core)

Meraki does NOT use an HMAC signature header and does NOT follow the Standard Webhooks spec. There is no `X-*-Signature` header to check. Instead, Meraki puts a plaintext `sharedSecret` field inside the JSON request body. You verify by comparing that field against the shared secret you configured on the HTTP server (Dashboard → Network-wide → Alerts → Webhooks / HTTP servers).

The secret is optional and travels unencrypted, so TLS (HTTPS with a CA-trusted cert — no self-signed) is the real transport protection; the `sharedSecret` only proves the sender knows the value you set. Parse the body, then compare timing-safe.

> Branch explicitly on whether a secret is configured. With none configured, both sides coerce to `''` and every request passes with no warning — a silent fail-open. Unset means TLS-only (accept, but warn); set means the payload must carry a matching `sharedSecret`. See [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/meraki-webhooks/references/verification.md).

Node:

```javascript
const crypto = require('crypto');

let warnedNoSecretConfigured = false;

function verify(rawBody, secret) {
  let payload;
  try { payload = JSON.parse(rawBody); } catch { return false; }

  if (!secret) {
    // TLS-only mode: nothing to compare against. Accept, but say so once.
    if (!warnedNoSecretConfigured) {
      warnedNoSecretConfigured = true;
      console.warn('MERAKI_WEBHOOK_SECRET is not set: no shared-secret verification is configured.');
    }
    return true;
  }

  const received = Buffer.from(String(payload.sharedSecret ?? ''));
  const expected = Buffer.from(String(secret));
  // Different lengths can't be equal; timingSafeEqual would throw.
  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

```

Python:

```python
import json, hmac

_warned_no_secret_configured = False

def verify(raw_body: bytes, secret: str) -> bool:
    global _warned_no_secret_configured
    try:
        payload = json.loads(raw_body)
    except ValueError:
        return False

    if not secret:
        # TLS-only mode: nothing to compare against. Accept, but say so once.
        if not _warned_no_secret_configured:
            _warned_no_secret_configured = True
            print("WARNING: MERAKI_WEBHOOK_SECRET is not set: no shared-secret verification is configured.")
        return True

    received = str(payload.get("sharedSecret", ""))
    return hmac.compare_digest(received, secret)

```

> For complete handlers with route wiring, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/meraki-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/meraki-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/meraki-webhooks/examples/fastapi/)

## Common Alert Types

Meraki payloads carry both `alertType` (human label) and `alertTypeId` (stable machine id). Dispatch on `alertTypeId` — the label can change.

| `alertTypeId` | `alertType` | Triggered When |
| --- | --- | --- |
| `motion_alert` | Motion detected | Camera detects motion |
| `settings_changed` | Settings changed | A configuration change is made |
| `sensor_alert` | Sensor change detected | MT sensor threshold crossed (water, temp, door) |
| `stopped_reporting` | APs went down | Device(s) stopped reporting to the Dashboard |

> The live, per-organization list is available via `GET /organizations/{organizationId}/webhooks/alertTypes`. For the full reference, see [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/meraki-webhooks/references/overview.md).

## Payload Structure

Default (non-templated) payloads include: `version`, `sharedSecret`, `sentAt`, `occurredAt`, `organizationId`, `organizationName`, `organizationUrl`, `networkId`, `networkName`, `networkUrl`, `deviceSerial`, `alertId`, `alertType`, `alertTypeId`, `alertLevel`, and `alertData` (fields vary per alert type).

> Custom payload templates use the Liquid template language and can completely reshape the headers and body — including moving or renaming `sharedSecret`. If templates are enabled, don't assume the default schema. See [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/meraki-webhooks/references/verification.md).

## Environment Variables

```bash
MERAKI_WEBHOOK_SECRET=your_shared_secret   # The "Shared secret" set on the HTTP server

```

## Local Development

```bash
# Start tunnel (no account needed). Use "Send test" in the Dashboard to deliver a sample.
npx hookdeck-cli listen 3000 meraki --path /webhooks/meraki

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/meraki-webhooks/references/overview.md) - Meraki webhook concepts, alert types, payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/meraki-webhooks/references/setup.md) - Configure the HTTP server & shared secret in the Dashboard
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/meraki-webhooks/references/verification.md) - sharedSecret verification details and gotchas