# Pusher Channels Webhooks

Covers **Pusher Channels** webhooks (channel presence, client events, cache and subscription events). Pusher Beams (push notifications) is a different product.

## When to Use This Skill

* How do I receive Pusher Channels webhooks?
* How do I verify the `X-Pusher-Signature` header?
* How do I handle `channel_occupied`, `channel_vacated`, `member_added` or `member_removed` events?
* How do I handle batched Pusher webhooks with several events in one request?
* Why is my Pusher webhook signature verification failing?

## Verification (core)

Pusher signs the **raw POST body** with HMAC-SHA256 keyed on the app secret and sends the lowercase hex digest in `X-Pusher-Signature`. `X-Pusher-Key` names the app key (token) used; an app can have several tokens and the oldest active one signs. There is no timestamp in the signature and no `sha256=` prefix.

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

function verify(rawBody, key, signature, tokens /* { [appKey]: appSecret } */) {
  const secret = tokens[key];
  if (!secret || !signature) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

```

The official SDKs wrap this: Node `pusher.webhook({ headers, rawBody }).isValid()` and Python `pusher_client.validate_webhook(key=..., signature=..., body=...)`. The examples use them. See [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pusher-webhooks/references/verification.md) for the SDK gotchas (exact `application/json` content type, Python's ±5 minute `time_ms` window) and a manual Python fallback.

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

## Payload and Batching

```json
{ "time_ms": 1327078148132, "events": [{ "name": "channel_occupied", "channel": "my-channel" }] }

```

`events` is an array. With **batch webhooks** enabled in the dashboard it can hold many events, so always iterate; never read `events[0]` only. Return 2xx quickly (queue slow work); non-2xx responses are retried with exponential backoff for 5 minutes.

## Common Event Types

| Event | Description |
| --- | --- |
| `channel_occupied` | A channel gets its first subscriber |
| `channel_vacated` | A channel loses its last subscriber |
| `member_added` | A user subscribes to a presence channel (`user_id`) |
| `member_removed` | A user unsubscribes from a presence channel (`user_id`) |
| `client_event` | A client event was sent on a private/presence channel (`event`, `data`, `socket_id`) |
| `cache_miss` | A client subscribed to a cache channel with no cached message |
| `subscription_count` | Subscriber count of a channel changed (`subscription_count`) |

> **For full event reference**, see [Pusher Channels webhooks](https://pusher.com/docs/channels/server_api/webhooks/)

## Important Headers

| Header | Description |
| --- | --- |
| `X-Pusher-Signature` | HMAC SHA256 hex digest of the raw body |
| `X-Pusher-Key` | App key (token) whose secret signed the body |
| `Content-Type` | `application/json` |

## Environment Variables

```bash
PUSHER_APP_ID=your_app_id
PUSHER_APP_KEY=your_app_key        # matches X-Pusher-Key
PUSHER_APP_SECRET=your_app_secret  # signs the webhook body
PUSHER_CLUSTER=mt1

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 pusher --path /webhooks/pusher

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pusher-webhooks/references/overview.md) - Pusher webhook concepts, event payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pusher-webhooks/references/setup.md) - Dashboard configuration
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/pusher-webhooks/references/verification.md) - Signature verification details