Skip to guide
Podyx Developers Studio API v2

STUDIO API / CAPABILITY GUIDES

Read Markdown ↗

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.

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. 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. 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.

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.

{
  "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 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:

  • 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 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 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.