# Chili Piper Webhooks

## When to Use This Skill

* How do I receive Chili Piper webhooks?
* How do I verify the Chili Piper `X-Chili-Signature` header?
* Why does my Chili Piper webhook signature verification fail?
* How do I handle Chili Piper meeting `Created`, `Updated` and `Deleted` events?
* How do I get my Chili Piper webhook signing secret?

## Get the Signing Secret

Chili Piper issues the signing secret on request: email Chili Piper support for your tenant's secret and paste it here.

The secret is not shown in the Command Center. Create and enable the webhook first, then email support@chilipiper.com with your tenant (instance) name and the webhook you created. Store it as `CHILI_PIPER_WEBHOOK_SECRET`. See [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chili-piper-webhooks/references/setup.md).

## Verification (core)

Every request carries `X-Chili-Signature` (lowercase hex HMAC-SHA256, no prefix) and `X-Chili-Timestamp` (Unix seconds). The signed message is the timestamp header value, a literal `.`, then the **raw request body bytes**. The key is the secret's UTF-8 bytes, used as-is (not hex- or base64-decoded).

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

function verifyChiliPiper(rawBody, signature, timestamp, secret) {
  if (!signature || !timestamp || !secret) return false;
  if (!/^[0-9a-fA-F]{64}$/.test(signature)) return false; // validate before decoding
  const signed = Buffer.concat([Buffer.from(timestamp, 'latin1'), Buffer.from('.'), rawBody]);
  const expected = crypto.createHmac('sha256', secret).update(signed).digest();
  return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

```

Build the signed message as bytes: never decode the body to a string and re-encode it, and never `JSON.parse`/`JSON.stringify` before verifying. Reject a missing, empty or malformed signature or timestamp, and a mismatch, with `401`.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/chili-piper-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/chili-piper-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/chili-piper-webhooks/examples/fastapi/).

## Timestamp Tolerance (opt-in)

Do not reject old timestamps by default. Hookdeck retries and replays resend the original headers and timestamp, and Hookdeck applies no tolerance itself, so a fixed window would reject legitimate retries. The examples check `X-Chili-Timestamp` against the clock only when `CHILI_PIPER_WEBHOOK_TOLERANCE_SECONDS` is set above 0 (unset or `0` = off). Chili Piper's own example uses 300 seconds.

## Event Types

Chili Piper sends one webhook per action type, selected when you create the webhook in the Command Center. The body's `type` field carries the event name. Dispatch on it.

| `type` | Webhook type | Triggered when |
| --- | --- | --- |
| `Created` | For New Meeting | A meeting is booked, from any source |
| `Updated` | For Meeting Update | A meeting is updated, for example reassigned or rescheduled |
| `Deleted` | For Canceled Meeting | A user or prospect cancels the meeting |

## Important Headers and Behavior

| Item | Value |
| --- | --- |
| `X-Chili-Signature` | Lowercase hex HMAC-SHA256 digest (64 characters), compared as a whole value |
| `X-Chili-Timestamp` | Unix timestamp in seconds when the request was signed |
| Method / body | `POST` with a JSON body. Read the raw body whatever the content type |
| Retries | Not documented. De-duplicate on `meetingIdChili` plus `type` |

## Environment Variables

```bash
CHILI_PIPER_WEBHOOK_SECRET=your_webhook_signing_secret   # issued by Chili Piper support
CHILI_PIPER_WEBHOOK_TOLERANCE_SECONDS=0                  # optional, 0 or unset disables the replay check

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chili-piper-webhooks/references/overview.md) - Webhook types, payload fields, delivery behavior
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chili-piper-webhooks/references/setup.md) - Create webhooks in the Command Center and obtain the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/chili-piper-webhooks/references/verification.md) - Signature details, replay protection, debugging