Agent skill

Segment Webhooks Skill

Receive and verify Twilio Segment webhooks from the Webhooks (Actions) and classic Webhooks destinations. Use when setting up a Segment webhook endpoint, verifying the X-Signature header (HMAC-SHA1 hex with the shared secret), debugging Segment signature verification failures on batched deliveries, or handling Segment spec calls like track, identify, page, screen, group, and alias.

Install this skill

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

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/, examples/nextjs/, 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 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 and Segment's Webhooks (Actions) docs.

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

SEGMENT_SHARED_SECRET=your_shared_secret   # Destination Settings → Shared Secret

Local Development

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

Reference Materials

references/overview.md - Segment webhook destinations, spec call types, payloads, retries
references/setup.md - Configure the destination, mapping, and shared secret
references/verification.md - X-Signature details, batching caveat, debugging