# 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.

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendbird-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendbird-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendbird-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendbird-webhooks/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

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

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendbird-webhooks/references/overview.md) - Sendbird webhook concepts and categories
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendbird-webhooks/references/setup.md) - Dashboard configuration
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/sendbird-webhooks/references/verification.md) - Signature verification details and gotchas