# OnceHub Webhooks

## When to Use This Skill

* How do I receive OnceHub webhooks?
* How do I verify the `Oncehub-Signature` header?
* How do I handle `booking.scheduled`, `booking.rescheduled`, or `booking.canceled` events?
* How do I react to `booking.completed` or `booking.no_show` events?
* Why does my OnceHub webhook have no signing secret (v1 vs v2)?
* Why is my OnceHub webhook signature verification failing?

## Verification (core)

OnceHub signs **v2** webhooks with an `Oncehub-Signature` header of the form `t=<unix seconds>,s=<hex>`.
`s` is the hex HMAC-SHA256 of `"<t>.<raw body>"`, keyed with the endpoint secret as a UTF-8 string
(Webhook & API integration > **View secret**). Always sign over the **raw body**.

**Only v2 webhooks are signed.** If the dashboard doesn't show **View secret** for the webhook, it is a
v1 webhook: it sends no signature and can't be verified. Create a new webhook (new ones are v2).

**Timestamp window is opt-in.** Hookdeck retries and replays resend the original timestamp, so a
5-minute window rejects late retries. It is controlled by `ONCEHUB_TIMESTAMP_TOLERANCE_SECONDS`
(default `0` = off); see [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oncehub-webhooks/references/verification.md) for where the window
can be dropped or widened.

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

// toleranceSeconds = 0 (default) skips the timestamp window; a positive value opts in
function verifyOncehubWebhook(rawBody, header, secret, toleranceSeconds = 0) {
  if (!header) return false;
  const parts = header.split(',').map((p) => p.split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  const sigs = parts.filter(([k]) => k === 's').map(([, v]) => v);
  if (!t || !/^\d+$/.test(t) || sigs.length === 0) return false;
  if (toleranceSeconds > 0 && Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  return sigs.some((sig) => {
    try { return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); }
    catch { return false; } // length mismatch
  });
}

```

OnceHub has no verification SDK, so verification is manual in every framework. 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/oncehub-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/oncehub-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/oncehub-webhooks/examples/fastapi/).

## Common Event Types

The body is a single JSON event (`id`, `object`, `creation_time`, `type`, `api_version`, `data`). Route on `type`:

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `booking.scheduled` | A booking is made | CRM record, confirmation flow |
| `booking.rescheduled` | A booking is rescheduled | Update calendar/CRM time |
| `booking.reassigned` | A booking is reassigned | Update owner |
| `booking.canceled_then_rescheduled` | Canceled, then rescheduled | Link old and new booking |
| `booking.canceled_reschedule_requested` | Canceled with a reschedule requested | Follow-up outreach |
| `booking.canceled` | A booking is canceled | Release resources |
| `booking.completed` | A booking is completed | Follow-up, billing |
| `booking.no_show` | A booking is marked no-show | No-show workflow |
| `conversation.started` / `conversation.closed` / `conversation.abandoned` | Conversation lifecycle | Lead routing |

Payload details are in [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oncehub-webhooks/references/overview.md).

## Environment Variables

```bash
ONCEHUB_WEBHOOK_SECRET=your_endpoint_secret   # Webhook & API integration > View secret (v2 webhooks only)
ONCEHUB_TIMESTAMP_TOLERANCE_SECONDS=0       # Optional replay window; a positive value opts in

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oncehub-webhooks/references/overview.md) - OnceHub webhook concepts, events, payload shape
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oncehub-webhooks/references/setup.md) - Create a webhook in OnceHub and get the secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/oncehub-webhooks/references/verification.md) - Signature verification details and gotchas