Agent skill

Pusher Channels Webhooks Skill

Receive and verify Pusher Channels webhooks. Use when setting up Pusher webhook handlers, debugging X-Pusher-Signature verification, or handling channel_occupied, channel_vacated, member_added, member_removed, client_event, cache_miss, and subscription_count events.

Install this skill

npx skills add hookdeck/webhook-skills --skill pusher-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.

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 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/, examples/nextjs/, examples/fastapi/.

Payload and Batching

{ "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

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

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

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

Reference Materials

references/overview.md - Pusher webhook concepts, event payloads
references/setup.md - Dashboard configuration
references/verification.md - Signature verification details