Agent skill

Sendbird Webhooks Skill

Receive and verify Sendbird Chat webhooks. Use when setting up Sendbird webhook handlers, debugging x-sendbird-signature verification, or handling events like group_channel:message_send, group_channel:create, group_channel:join, open_channel:message_send, or user:block.

Install this skill

npx skills add hookdeck/webhook-skills --skill sendbird-webhooks

When to Use This Skill

How do I receive Sendbird webhooks?
How do I verify the x-sendbird-signature header?
Why is my Sendbird webhook signature verification failing (master vs secondary API token, raw body)?
How do I handle group_channel:message_send or user:block events?

Verification (core)

Sendbird sends x-sendbird-signature: the hex HMAC-SHA256 of the raw body, keyed with the application's master API token (secondary API tokens don't work). Use x-sendbird-signature, not the legacy x-signature, which breaks on non-ASCII bodies. The master token is a full-access credential: keep it server-side only.

const crypto = require('crypto');

function verify(rawBody, signatureHeader, apiToken) {
  if (!signatureHeader || !apiToken) return false;
  const expected = crypto.createHmac('sha256', apiToken).update(rawBody).digest('hex');
  const received = Buffer.from(signatureHeader.trim().toLowerCase());
  const expectedBuf = Buffer.from(expected);
  return received.length === expectedBuf.length && crypto.timingSafeEqual(received, expectedBuf);
}

In Express read the body with express.raw({ type: '*/*' }) so any content type verifies.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

The event type is the category field in the JSON body.

Category	Description
`group_channel:message_send`	Message sent in a group channel
`group_channel:create`	Group channel created
`group_channel:join`	User joins a group channel
`group_channel:leave`	User leaves a group channel
`open_channel:message_send`	Message sent in an open channel
`user:block`	User blocks another user
`user:unblock`	User unblocks another user

See references/overview.md for the full category list.

Important Headers

Header	Description
`x-sendbird-signature`	Hex HMAC-SHA256 of the raw body (use this)
`x-signature`	Legacy; mismatches on non-ASCII bodies, do not use
`user-agent: SendBird`	Sender identification

Sendbird waits 5 seconds and retries up to three times: respond 200 fast and process asynchronously.

Environment Variables

SENDBIRD_API_TOKEN=your_master_api_token   # Dashboard > Settings > Application > General (master token, not secondary)

Local Development

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

Reference Materials

references/overview.md - Sendbird webhook concepts and categories
references/setup.md - Dashboard configuration
references/verification.md - Signature verification details and gotchas