Webhooks

Webhooks are a powerful tool for integrating your applications with the Unified Fitness Platform (UFP). They allow you to receive real-time HTTP notifications about events that happen in your locations, such as a new lead being created, an invoice being paid, or a client being flagged as at-risk.

By subscribing to these events, you can automate workflows, sync data with external systems, trigger custom notifications, and much more.

Key Concepts: Global vs. Location Webhooks

You can configure webhooks at two different levels, depending on your needs.

Global Webhook (Company Level)

Receive event notifications from all locations under your brand through a single, centralized webhook.

Use Case: Ideal for centralized systems that need a complete overview of all brand activity, such as a company-wide analytics dashboard or a central data warehouse.

Tenant Webhook ( Specific Tenant)

Receive event notifications only from this specific location, allowing for more granular control.

Use Case: Perfect for actions tied to a single facility, like notifying a location-specific sales team about a new lead or managing access control for one gym.

Setup and Configuration Guide

Follow these steps to set up your webhook endpoint.

Navigate to Webhook Settings

Go to Settings in the main navigation menu.

Click on Webhooks.

Choose Your Webhook Type

Select either Global Webhook or Location Webhook based on your requirements.

Configure Your Endpoint

WEBHOOK URL: Enter the public URL of your application's endpoint that will receive the webhook POST requests from UFP.

SECRET KEY: Enter a secret key. This can be any random string you choose. It will be used to generate a signature for each payload, allowing you to verify its authenticity.

Store your Secret Key securely. You will need it to verify all incoming webhooks.

Subscribe to Events

After saving your URL and secret, you will see a list of all available events.

Click the Subscribe button next to each event you want to receive notifications for. You can update your subscriptions at any time.

Verifying Payload Signatures

To ensure that webhook requests are authentic and have not been tampered with, UFP signs every payload. The signature is sent in the X-UFP-Signature HTTP header.

You must verify this signature on your server. To do this, generate a HMAC-SHA256 hash using the raw JSON payload from the request body and your securely stored Webhook Secret Key.

Verification Steps:

Extract the signature from the X-UFP-Signature header of the incoming request.

Read the raw request body. Important: Use the raw body, not a parsed JSON object.

Compute the HMAC-SHA256 hash of the raw request body, using your Webhook Secret Key as the key.

Compare your generated hash (in hex format) with the signature from the header. If they match, the request is valid.

Code examples for verification are provided in the Best Practices section below.

Payload Structure

All webhook events are sent as a POST request with a JSON body. The structure is as follows:

{
  "webhook_event_type": "new_lead_created",
  "created_at": "11/06/2025 17:22",
  "company_id": 1,
  "tenant_id": 2,
  "payload": {
    "tenant_name": "DEMO TENANT - T1",
    "client_name": "Campaign",
    "phone": "+917455256585",
    "email": "vimit@fitnessforce.com",
    "gender": "Male",
    "dob": "11/06/2000",
    "source": "Referral",
    "channel": "WalkIn",
    "client_rep_name": "Nitin Yadav",
    "created_date_time": "11/06/2025 17.22",
    "client_status": "Prospect",
    "external_id": "",
    "migration_id": "",
    "created_by": 858,
    "track_mode": "StaffWebApp",
    "is_child": "False",
    "relation": "None",
    "parent_id": 0,
    "clt_cp_client_id": ""
  }
}

webhook_event_type (string): The key of the event that was triggered.

created_at (string): The timestamp of when the event occurred.

tenant_id (integer): The ID of the location where the event originated.

payload (object): A JSON object containing the specific data for the event. The structure of this object is different for each event_type.

Webhook Reliability: Retries and Disabling

It is critical that your application correctly handles incoming webhooks to ensure uninterrupted service.

Acknowledging Events

Your endpoint must return a 2xx HTTP status code (e.g., 200 OK, 202 Accepted) to signal that you have successfully received the event. This should be done as quickly as possible. If your application needs to perform long-running tasks, process them asynchronously in a background job after sending the 2xx response.

Automatic Retry Policy

If your endpoint fails to return a 2xx response (due to a server error, network timeout, or any 4xx/5xx response), UFP will consider the delivery a failure and initiate a retry process.

We will attempt to redeliver the event 3 more times over the next 24 hours.

The time interval between retries will increase with each failed attempt.

Webhook Disabling

⚠️ IMPORTANT: Failure to Acknowledge Events
If all retry attempts for a single event fail, your webhook will be automatically disabled.
A disabled webhook will stop receiving all subsequent event notifications. No new webhooks will be sent to the configured URL until it is manually re-enabled in the UFP admin settings. It is essential to build a resilient endpoint that can handle these requests reliably to avoid service disruption.

Best Practices & Code Examples

1. Respond Immediately, Process Asynchronously

Acknowledge the webhook with a 200 OK before doing any complex processing to avoid timeouts.

2. Verify Signatures

Always verify the signature before trusting the payload.

Node.js

Python (with Flask)

3. Handle Event Idempotency

It is possible to receive the same event more than once due to retries. Design your system to be idempotent.

4. Secure Your Secret Key

Treat your webhook secret key like any other password. Store it securely as an environment variable or in a secrets management tool. Do not hardcode it in your application's source code.

Available Webhook Events

The following is a list of events you can subscribe to. For the most current and detailed list, please visit the webhook configuration section in your UFP staff application:

https://{your_site_subdomain}.staff.unifiedfitnessplatform.ai/#/admin/webhook-configuration/company

Event Key	Description	Category
Sales & Leads
`newlead_created`	Triggered when a new lead is created in the system.	Sales
`repeat_enq_created`	Triggered when an existing lead or client makes a new enquiry.	Sales
`tour_booked`	Triggered when a facility tour is booked for a lead.	Sales
`tour_marked_noshow`	Triggered when a lead is marked as a no-show for their scheduled tour.	Sales
`trial_created`	Triggered when a new trial period is created for a client.	Sales
`sub_signup_link_generated`	Triggered when a unique subscription signup link is created.	Sales
Subscriptions
`sub_signup_completed`	Triggered when a client successfully completes the signup process for a subscription.	Subscriptions
`sub_signup_failed`	Triggered when a client's subscription signup process fails.	Subscriptions
`sub_cancellation_requested`	Triggered when a client requests to cancel their subscription.	Subscriptions
`sub_freeze_created`	Triggered when a subscription is successfully frozen.	Subscriptions
`sub_freeze_voided`	Triggered when a subscription freeze is voided or cancelled by an admin.	Subscriptions
`sub_freeze_stopped`	Triggered when a subscription freeze ends and the subscription becomes active again.	Subscriptions
`sub_voided`	Triggered when an active subscription is voided by an admin.	Subscriptions
`transferor_consent_request_initiated`	Triggered when a consent request for transferring a subscription is initiated.	Subscriptions
Billing & Payment
`invoice_created`	Triggered when a new invoice is created.	Billing & Payment
`invoice_voided`	Triggered when an existing invoice is voided.	Billing & Payment
`recurring_payment_received`	Triggered when a recurring payment is successfully processed.	Billing & Payment
`recurring_payment_failed`	Triggered when a recurring payment attempt fails.	Billing & Payment
`non_recurring_payment_received`	Triggered when a non-recurring (one-off) payment is successfully received.	Billing & Payment
`non_recurring_payment_failed`	Triggered when a non-recurring payment attempt fails.	Billing & Payment
`payment_voided`	Triggered when a completed payment record is voided.	Billing & Payment
`sales_return_created`	Triggered when a sales return is initiated.	Billing & Payment
`sales_return_voided`	Triggered when a sales return is voided.	Billing & Payment
`refund_processed`	Triggered when a refund has been successfully processed for a payment.	Billing & Payment
Appointments
`single_appt_booked`	Triggered when a single (non-recurring) appointment is booked.	Appointments
`single_appt_cancelled`	Triggered when a single appointment is cancelled.	Appointments
`single_appt_rescheduled`	Triggered when a single appointment is rescheduled.	Appointments
`single_appt_marked_attended`	Triggered when a client is marked as 'attended' for an appointment.	Appointments
`single_appt_marked_noshow`	Triggered when a client is marked as a 'no-show' for an appointment.	Appointments
`recurring_appt_booked`	Triggered when a recurring series of appointments is booked.	Appointments
`recurring_appt_cancelled`	Triggered when a series of recurring appointments is cancelled.	Appointments
`recurring_appt_rescheduled`	Triggered when a series of recurring appointments is rescheduled.	Appointments
Classes
`class_booked`	Triggered when a client books a spot in a class.	Classes
`class_booking_cancelled`	Triggered when a client cancels their booking for a specific class session.	Classes
`class_cancelled`	Triggered when an entire class schedule (e.g., all future sessions) is cancelled by an admin.	Classes
`class_rescheduled`	Triggered when a class session is rescheduled to a new time or date.	Classes
`class_marked_attended`	Triggered when a client's attendance is marked for a class.	Classes
`class_marked_noshow`	Triggered when a client is marked as a 'no-show' for a class.	Classes
`class_waitlist_spot_vacated`	Triggered when a spot opens up in a fully booked class that has a waitlist.	Classes
`class_coach_substituted`	Triggered when the coach for a scheduled class is changed.	Classes
Client Management & Retention
`waiver_completed`	Triggered when a client signs and completes a liability waiver.	Client Management
`flagged_clt_at_risk`	Triggered when a client is manually flagged as being 'at risk' of churning.	Retention
`app_booking_restricted`	Triggered when a client's booking privileges are restricted by an admin.	Client Management
`app_booking_restriction_lifted`	Triggered when a client's booking restriction is removed.	Client Management
`clt_birthday`	Triggered on a client's birthday.	Notifications
`tour_scheduled_date`	Triggered on the day a facility tour is scheduled to occur.	Notifications
`trial_start_date`	Triggered on the day a client's trial period is scheduled to begin.	Notifications
`trial_end_date`	Triggered on the day a client's trial period is scheduled to end.	Notifications
`sub_cancellation_date`	Triggered on the date a subscription is scheduled to be officially cancelled.	Notifications
`sub_freeze_start_date`	Triggered on the day a subscription freeze is scheduled to begin.	Notifications
`sub_freeze_end_date`	Triggered on the day a subscription freeze is scheduled to end.	Notifications
`class_session_date`	Triggered on the day of a scheduled class session (can be used for reminders).	Notifications

Key Concepts: Global vs. Location Webhooks#

Global Webhook (Company Level)#

Tenant Webhook ( Specific Tenant)#

Setup and Configuration Guide#

Verifying Payload Signatures#

Verification Steps:#

Payload Structure#

Webhook Reliability: Retries and Disabling#

Acknowledging Events#

Automatic Retry Policy#

Webhook Disabling#

Best Practices & Code Examples#

1. Respond Immediately, Process Asynchronously#

2. Verify Signatures#

3. Handle Event Idempotency#

4. Secure Your Secret Key#

Available Webhook Events#