# Webhooks

Receive signed notifications when sessions change, clients join a studio, or bookings and purchases are paid, cancelled or refunded.

## Set up a destination

A studio owner opens **Settings → Integrations → Webhooks** and adds a public HTTPS destination. Webhooks are available to studios with REST API access and webhook delivery enabled. Use HTTPS on port 443 and a receiver that can accept POST requests directly.

Copy the one-time `whsec_` signing key into the receiver's secret store. **Require endpoint verification** defaults to **Enabled** for every destination. Choose **Verify destination** after the receiver is ready. Podyx sends a signed request with `type: "webhook.verification"`. Verify its signature with the same procedure as a session event, then reply with a `2xx` status and JSON containing the exact `nonce` from the request. The challenge expires after 15 minutes. A successful verification activates the destination. Refresh the panel to check the result.

If you control the destination URL and your receiver cannot echo a nonce, set **Require endpoint verification** to **Disabled**. The setting saves automatically. When the status changes to **Pending activation**, choose **Activate destination**. Podyx still signs every event. Verify its signature before processing it. Requiring verification again on a destination activated without a challenge suspends delivery until verification succeeds. Queued deliveries for the previous destination generation are retired, and a request already being sent may finish.

Pause stops new sends to the destination. Use **Resume and verify** when verification is enabled or **Resume delivery** when it is disabled. Replacing a URL retains the verification setting, stops new sends and issues a fresh signing key. Set up the new receiver and verify or activate it before delivery resumes. Run a baseline read after activation or resumption.

When order webhooks are enabled for your studio, choose **Receive order events** on an active destination to allow payment, refund and promo-code information to be sent there. Each destination starts with session events only. **Stop order events** retires its queued order deliveries and their replay eligibility. An attempt already admitted for sending may still finish. Opt a replacement URL into order events separately.

When client webhooks are enabled for your studio, set **Client events** to **Enabled** on an active destination to receive `client.created`. The setting saves automatically. Disabling it retires queued client events and their replay eligibility. An attempt already admitted for sending may still finish. Enable client events again if you replace the URL.

### Client contact details

In the destination panel, **Include client contact details** controls the optional top-level `client_contact` object for session, order and client events. Only studio owners can change this setting. It starts enabled for newly added destinations. Destinations already configured before this release start disabled. Replacing a URL turns sharing off until an owner enables it for the replacement. Turn the setting off before activating destinations that do not need personal information.

When sharing is enabled and a studio client can be resolved at capture time, the object contains `name`, `email` and `phone`. An unavailable field is null. If the event has no eligible client, or the destination does not share contact details, the object is omitted. Only share contact details with endpoints approved to store them.

Disabling sharing retires queued deliveries and replay eligibility for bodies that contain contact details. A request already admitted for delivery may finish. Deliveries captured without contacts keep their original body. Re-enabling sharing applies to new captures. Podyx also suppresses contact-bearing delivery or replay if the client is no longer eligible for sharing at send time.

## Session events

| Event | When it is sent |
| --- | --- |
| `session.scheduled` | A session becomes confirmed. |
| `session.rescheduled` | A confirmed session's local date, start or end changes. |
| `session.updated` | An applied Edit Session or a standalone mutation changes session details. |
| `session.cancelled` | Cancellation of a previously confirmed session commits. |
| `session.deleted` | A session is deleted. Deleting a booking sends one event per removed session. |

All session events include `id`, `type`, `schema_version`, `occurred_at`, `studio_id`, `booking_id`, `session_id` and `schedule`. The occurrence timestamp is UTC. The schedule has a local `date`, `start_time`, `end_time` and IANA `timezone`. Cancelled or deleted sessions carry their last schedule. Timing changes also include `previous_schedule`.

Updates carry a sorted, unique `changed_sections` array. Its values are `addons`, `billing`, `crew`, `file_transfer`, `form_answers`, `guests`, `links`, `notes`, `pricing`, `recording_seats`, `room_setup`, `schedule`, `service` and `staff`. Each applied edit lists the sections that actually changed. A change to or from no seat count lists `recording_seats`. A timing-changing edit to a confirmed session produces both an update and a reschedule with distinct IDs. Payment- or approval-dependent edits emit at application.

A standalone staff move that changes only the date or time of a confirmed session sends `session.rescheduled` only.

A separate add-on purchase can send `session.updated` with `addons` when the purchase is recorded and again when payment settles. The event identifies the session. If your integration created the purchase, use the `resource_id` from the creation response to [read its payment and approval status](/api/docs#/Studio%20booking%20aftercare/v2AftercareAddon).

Newly captured session events include a `session` object with `client_id`, `studio_name`, `service_name`, `room_name`, `duration_minutes`, `amount`, `currency`, `booking_source` and `status`. The service name comes from the recorded service version or snapshot and the room name from the room at capture time. Roomless tours have a null room. The amount is the recorded session allocation or snapshot total. If only a service or tour price was recorded, it is that charge line. Amounts are decimal strings in major currency units and do not measure money collected. An allocated package amount uses the recorded package currency. Unavailable amounts or currencies are null. The booking source is `individual`, `bundle`, `subscription` or `studio_tour`. A cancelled or deleted event names that session state explicitly.

Read note text, rosters, link URLs and full payment data through [permission-aware API reads](/api/docs/guides/v2/access). Treat section names as signals to refresh data.

## Order events

| Event | When it is sent |
| --- | --- |
| `booking.paid` | A confirmed booking has a recorded, completed collection. |
| `booking.cancelled` | Cancellation of the booking commits. An individual session cancellation has its own session event. |
| `booking.refunded` | Podyx records money or credits returned against the booking, including a completed refund on an earlier collected checkout attempt. |
| `purchase.paid` | The initial bundle or subscription purchase, or a separately sold add-on, has a recorded, completed collection. |
| `purchase.cancelled` | The sold entitlement is cancelled. For subscriptions ending at the end of their term, the event is sent when the cancellation takes effect. |
| `purchase.refunded` | Podyx records a completed return against the separate purchase. |

An authorization, a pending payment or a provider's acceptance of a refund request can precede settlement. A booking sale uses the `booking.*` events even when the booking also appears in the purchases list. A subscription's order covers its initial purchase. Subsequent renewals have their own billing lifecycle.

Paid events require the order's `payment_status` to be `paid`. Cash orders with `payment_status: "outside_podyx"` send no paid event, even when the studio has confirmed the booking or approved the purchase.

The envelope includes `id`, `type`, `schema_version`, `occurred_at`, `studio_id`, `order_id` and `order`. The envelope's `order_id` matches the stable `id` in the [v2 order lists](/api/docs/guides/v2/orders). The nested `order.order_id` is the studio's displayed order reference. The nested row includes `kind`, `client_id`, order status, payment and refund status, monetary amounts as decimal strings, and `promo_code_id`, `promo_code`, `promo_code_source` and `promo_discount_amount`. Client contact details, when shared, are in the top-level envelope. When there is no saved promo text, `current` identifies text looked up at capture time. Receivers can match on the promo ID across renames.

A wallet hold released when a booking expires does not contribute to the order's collected or refunded amount.

Each signed body reflects the order at capture time. Refund amounts are cumulative, so a later partial refund can produce another refund event with a new ID. Use the v2 order lists for a baseline and to reconcile current state after missed or out-of-order delivery. Filter by the original `ordered_at` date when re-reading a refunded order.

## Client events

`client.created` is captured when a human client first joins the studio through signup, sign-in, or a studio or API client-creation flow. A person with an existing Podyx account can trigger this event by joining a new studio. Subsequent sign-ins, profile edits and personnel onboarding produce no client event. Enabling client events sends future associations only. For an existing client baseline, use [Clients](/api/docs/guides/v2/clients).

Use `studio_id` and `client_id` as the key for an upsert in the receiving system. An opted-in destination also receives the contact fields if sharing is enabled.

```json
{
  "id": "8b4e6f75-cd48-47ee-8078-1ace624203ca",
  "type": "client.created",
  "schema_version": 1,
  "occurred_at": "2026-11-16T12:00:00Z",
  "studio_id": "4d6d8b4f-bd55-4c23-ac3d-531219799410",
  "client_id": "665ebf46-555e-40b3-8fe1-5b6f4f08b032",
  "client_contact": {
    "name": "Alex Example",
    "email": "alex@example.com",
    "phone": null
  }
}
```

## Package context

A package-backed session or an order for the package itself can include a top-level `package` object. A bundle reports `kind: "bundle"`, `id`, `name`, `unit_duration_minutes`, `purchased_units`, `remaining_units`, `purchased_minutes`, `remaining_minutes` and `expires_at`. Minute totals are null when the duration per unit is unavailable. Balances reflect the facts committed at capture, including the redemption on a newly scheduled package session. A subscription reports `kind: "subscription"`, `id`, `name`, `status` and `next_renewal_at` when a renewal is scheduled. These are snapshots and can be followed by later balance adjustments.

The [v2 OpenAPI contract](/api/openapi-v2.json) publishes the `SessionWebhookEvent`, `OrderWebhookEvent` and `ClientWebhookEvent` schemas. New fields are additive, and older deliveries and replays retain the original captured shape.

## Verify the signature

Save the original HTTP body bytes before parsing JSON. Use the [Standard Webhooks signing format](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md):

- `webhook-id` is the stable event ID and matches `id` in the body.
- `webhook-timestamp` is the Unix timestamp in seconds for this delivery attempt. Allow a clock difference of at most five minutes.
- `webhook-signature` contains one or more space-separated `v1,<base64>` signatures.

Remove the `whsec_` prefix and Base64-decode the signing key. Compute HMAC-SHA256 over `webhook-id.webhook-timestamp.` followed by the raw body bytes. Compare the calculated digest with the decoded signature using a constant-time comparison. During rotation Podyx can send a signature from both keys for up to 24 hours. The owner can also revoke the previous key immediately.

Use the separate studio API key for REST calls. The signing key stays in your receiver's secret store.

## Handle duplicates and refresh affected dates

Delivery is at least once and can arrive out of order. Each attempt keeps the original event ID and JSON bytes and uses a fresh attempt timestamp. After verifying the request, persist the event ID and queue your reconciliation work in the same durable transaction. Acknowledge with `2xx` after that commit. A duplicate can be acknowledged once the original work is durable.

Refresh each affected studio and date by calling [List studio sessions](/api/docs#/Studio%20operations/v2ListSessions) with equal `date_from` and `date_to`, `status=confirmed` and the includes your integration needs. On a move, refresh both the old and new dates. Fetch every session page and all required guest pages. A failed page or withheld required section leaves the previous complete projection in place. Serialize refreshes for each studio and date. If the date changes again while a read is in progress, queue another refresh. When replacing rows for the old date, scope the replacement to that date so the moved session remains on its new date.

Baseline the dates your workflow uses and reconcile them daily to recover from missed delivery and changes during pagination. See [Bookings & sessions](/api/docs/guides/v2/bookings) for filters, includes and scopes.

## Recover delivery

Podyx emails studio owners and shows a warning in the CMS when a destination is automatically deactivated or a delivery reaches its retry limit. Retry exhaustion alerts are limited to one per destination in 24 hours for the current configuration. Review the destination and delivery history under **Settings → Integrations → Webhooks**.

Podyx retries transient network errors, `429` and `5xx` with bounded backoff for up to 72 hours. `410 Gone` deactivates the current destination. Other client errors and unsafe destinations are visible in delivery history. An eligible failed delivery can be replayed to the same active destination for up to 14 days from the original delivery. Replay uses the same event ID. Delivery history is retained for 30 days. Use a reconciliation read to repair receiver state after an event has already been acknowledged.

## Example

This event says to refresh both local days for a rescheduled session:

```json
{
  "id": "18314b74-657e-49e7-acf1-e7b6aac91063",
  "type": "session.rescheduled",
  "schema_version": 1,
  "occurred_at": "2026-11-10T14:30:00Z",
  "studio_id": "4d6d8b4f-bd55-4c23-ac3d-531219799410",
  "booking_id": "f1626bdb-7ab5-4928-83f3-b443eac3fd75",
  "session_id": "1ab8a52a-c384-4221-acc7-9fa6974d6905",
  "schedule": {
    "date": "2026-11-13",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "timezone": "Europe/Madrid"
  },
  "previous_schedule": {
    "date": "2026-11-12",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "timezone": "Europe/Madrid"
  },
  "session": {
    "client_id": "665ebf46-555e-40b3-8fe1-5b6f4f08b032",
    "studio_name": "Example Studio",
    "service_name": "Podcast recording",
    "room_name": "Room A",
    "duration_minutes": 60,
    "amount": "90.00",
    "currency": "EUR",
    "booking_source": "bundle",
    "status": "confirmed"
  },
  "package": {
    "kind": "bundle",
    "id": "64410e6b-450b-48eb-969c-83dd2a360c41",
    "name": "Five recording sessions",
    "unit_duration_minutes": 60,
    "purchased_units": 5,
    "remaining_units": 3,
    "purchased_minutes": 300,
    "remaining_minutes": 180,
    "expires_at": "2027-01-01T00:00:00Z"
  },
  "client_contact": {
    "name": "Alex Example",
    "email": "alex@example.com",
    "phone": null
  }
}
```

In Node.js, pass the original body buffer and lower-case request headers to this function. A thrown error means the receiver should reject the request before recording the event:

```javascript
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPodyxWebhook(rawBody, headers, secret, now = Date.now()) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];

  if (
    typeof id !== "string" || !id ||
    typeof timestamp !== "string" || !/^\d{1,12}$/.test(timestamp) ||
    typeof signatures !== "string" || !secret.startsWith("whsec_") ||
    Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300
  ) {
    throw new Error("Invalid webhook headers");
  }

  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();

  const verified = signatures.split(" ").some((value) => {
    const [version, encoded] = value.split(",");
    if (version !== "v1" || !encoded) return false;
    const received = Buffer.from(encoded, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });

  if (!verified) throw new Error("Invalid webhook signature");

  const event = JSON.parse(rawBody.toString("utf8"));
  if (event.id !== id || event.schema_version !== 1) {
    throw new Error("Unsupported webhook envelope");
  }
  return event;
}
```

For a verified challenge, return JSON `{"nonce": event.nonce}`. For a verified session event, store the ID and enqueue refreshes for `event.schedule.date` and, when present, `event.previous_schedule.date` before acknowledging the request.
