Kustomer Webhooks Skill

When to Use This Skill

• How do I receive Kustomer outbound webhooks?
• How do I verify the X-Kustomer-Webhook-Signature header?
• How do I handle kustomer.conversation.create or kustomer.message.create events?
• Why is my Kustomer webhook signature verification failing?
• Why did Kustomer turn my outbound webhook off?

Verification (core)

Kustomer signs the raw request body with HMAC-SHA256, keyed with the webhook's secret (the token field from POST /v1/outbound-webhooks, also shown in Settings > Platform > Outbound webhooks > Edit > Header Information). The lowercase hex digest is sent in X-Kustomer-Webhook-Signature. There is no timestamp and no prefix. Kustomer has no webhook SDK, so verification is manual.

Node:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

Python:

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header.encode(), expected.encode())

Read the body as raw bytes (express.raw({ type: '*/*' })) so any content type verifies.

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Common Event Types

The event type is the name field in the JSON body (there is no event-type header).

For payload samples, see Kustomer outbound webhooks

Important Headers

Environment Variables

KUSTOMER_WEBHOOK_SECRET=your_webhook_token   # "token" of the outbound webhook

Local Development

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

Reference Materials

• references/overview.md - Kustomer webhook concepts and payload shape
• references/setup.md - Configuration guide
• references/verification.md - Signature verification details