# Segment Webhooks

## When to Use This Skill

* How do I receive Segment webhooks (Webhooks (Actions) or classic Webhooks destination)?
* How do I verify the Segment `X-Signature` webhook header?
* Why does Segment signature verification fail when batching is enabled?
* How do I handle Segment `track`, `identify`, `page`, `screen`, `group`, and `alias` calls?

## Verification (core)

Signing is **optional**. When you set a **Shared Secret** on the destination, Segment sends `X-Signature`: a **hex-encoded HMAC-SHA1** of the request body keyed with that secret. No timestamp, no prefix. Verify against the **raw body**.

**Batching caveat:** when batching is enabled, the body is a JSON array but Segment signs **only the first event** (`JSON.stringify(batch[0])`), not the whole body. A raw-body HMAC check fails for every batched delivery, so fall back to signing the first element. Only that first event is authenticated.

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

function verifySegmentSignature(rawBody, signature, secret) {
  if (!signature || !secret) return false;
  const matches = (content) => {
    const expected = crypto.createHmac('sha1', secret).update(content, 'utf8').digest('hex');
    try {
      return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
    } catch {
      return false; // length mismatch
    }
  };
  if (matches(rawBody)) return true; // single event: signature covers the raw body
  try {
    const parsed = JSON.parse(rawBody); // batch: Segment signs only the first event
    return Array.isArray(parsed) && parsed.length > 0 && matches(JSON.stringify(parsed[0]));
  } catch {
    return false;
  }
}

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/segment-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/segment-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/segment-webhooks/examples/fastapi/). The FastAPI example slices the first event's exact bytes from the raw body instead of re-serializing.

## Common Event Types

Segment forwards [Segment spec](https://segment.com/docs/connections/spec/) calls. Dispatch on the payload's `type` field:

| `type` | Description |
| --- | --- |
| `track` | User action; name in `event`, data in `properties` |
| `identify` | User traits in `traits` |
| `page` | Web page view; `name` and `properties` (path, url, referrer) |
| `screen` | Mobile screen view; `name`, `properties` |
| `group` | User joined a group/account; `groupId`, `traits` |
| `alias` | Merges identities; `previousId` → `userId` |
| `delete` | Classic Webhooks destination only: user deletion request notification |

With Webhooks (Actions), the **Data** mapping defaults to the whole event (`$.`); a custom mapping can change the body shape, so `type` may be absent.

> **For full payloads**, see [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/segment-webhooks/references/overview.md) and [Segment's Webhooks (Actions) docs](https://www.twilio.com/docs/segment/connections/destinations/catalog/actions-webhook).

## Important Headers

| Header | Description |
| --- | --- |
| `X-Signature` | HMAC-SHA1 hex of the body (or of the first event in a batch); only sent when a Shared Secret is set |
| `Content-Type` | `application/json` |
| `User-Agent` | `Segment.io/1.0` (classic destination) |

## Environment Variables

```bash
SEGMENT_SHARED_SECRET=your_shared_secret   # Destination Settings → Shared Secret

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/segment-webhooks/references/overview.md) - Segment webhook destinations, spec call types, payloads, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/segment-webhooks/references/setup.md) - Configure the destination, mapping, and shared secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/segment-webhooks/references/verification.md) - X-Signature details, batching caveat, debugging