Webhooks & event types

Nathan Skwortsow
Nathan Skwortsow
Last updated 
Physitrack lets you register a URL that is notified when a specific event, either automatically or manually triggered, happens to a client that belongs to a practitioner in your account. This is referred to as a webhook.

Registering a webhook

Physitrack's API has 2 environments available:

You should prepare one webhook URL per environment to your API consumer account, as this will allow you to have keep your testing and production environments separate.

Physitrack can call the following discrete webhooks:

  • new_client_created
  • new_program_assigned
  • program_updated
  • program_accessed
  • program_ended
  • new_message
  • call_ended
  • new_data_export
You can choose to use the same URL for all webhooks.

To register your webhooks, please send the URLs that you want registered to your technical contact with Physitrack. 
Please make sure that the webhook returns a 200 rest requests before sending us the URLs.


  • All requests are sent as HTTP POST over https
  • Your webhook should return an http 200 status within 5 seconds (please run processing asynchronously to avoid delays)
  • Any other information returned in the request headers or request body is ignored. All response codes other than 200, including 3xx codes, will indicate to Physitrack that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure.
  • Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed by logging the event_id, and then not processing already-logged events. 
If Physitrack does not receive a 200 status within 5 seconds, Physitrack will call the webhook one more time after 10 minutes. Webhooks cannot be manually retriggered, but you can use our API to query for missing data to reconcile your data with missed events.


Each HTTP request sent by Physitrack will include the practitioner API key in the header X-Api-Key so that you can authenticate the request.

Event attributes

  • Data is sent as JSON in the POST request body.
  • For your convenience, when an event is triggered, the event object is sent directly to the webhook. For example, if a new message has been sent by a client, the Event object will contain the new message object. This will limit unnecessary chatter between your system and the Physitrack API.
  • In any case, you can retrieve an individual event or a list of events from our API to reconcile data, if for example your webhook was unavailable.
All event objects share a common structure. They differ in the  data property.

The notification contains an Event object that contains: 

  • id
    String. Unique identifier for the event.
  • type
    String. Description of the event type, e.g. client_program_updated
  • created
    UNIX timestamp. Time at which the event was created.
  • data
    Hash. Object containing data associated with the event. See under Event types for sample data.
  • url
    The URL to retrieve this specific object.
You might then use this notification to trigger a call to our API to retrieve more details about this event.

Example of a new_message event sent to a webhook:

  "id": "1234567986",
  "type": "new_message",
  "created": "1425489787",
  "data": {
    "message_id": "12345678997",
    "sender_type": "client",
    "sender_email": "null",
    "timestamp": "1789456789",
    "pain_level": "6",
    "exercise_name": "Squats",
    "exercise_id": "123456",
    "access_code": "abcdabcd",
    "video_call": "false",
    "call_duration": "null",
    "body": "This was quite painful."
  "url": "/v2/clients/123454/messages/12345678997"

Event types

Some API events may trigger multiple events (and in turn, multiple calls to your webhook).
The descriptions below contain sample JSON output for the data.object object in the parent event object.

New client created

When a new client has been created inside your API namespace, either  programmatically via the API, or manually via the iframe or regular Physitrack.

  "pt_client_id": 123456789,
  "internal_id": 122265,
  "first_name": "John",
  "last_name": "Doe",
  "gender": "m",
  "year_of_birth": 1977,
  "email": "email@example.com",
  "mobile_phone": "0012125551212"

All 4 program-related events below all send back a program object, with irrelevant fields set tonull.

New program assigned to client

When a new access code has been assigned to a client (i.e. when the first exercise group has been added to a program). 
One access code can contain one or more exercise groups.

  "program_id": "123335",
  "patient_external_id": "123456",
  "meta_id": "1232555",
  "template_id": "1235",
  "program_name": "ACL Rehab Phase 2",
  "access_code": "abcdabcd",
  "sso_url": https://login.example.com?param=x
  "start_date": "15658985598",
  "end_date": "1234324343",
  "track_adherence": "false",
  "track_pain_levels": "false",
  "access_code_sent_date": "124578797987",
  "access_code_sent_via": "sms",
  "last_access_date": "124878745545",
  "event_initiator_id": "12345678",
  "program_assigner_id": "12345678"

Client's program updated

This event is triggered when a client's program has been updated. This includes if a new exercise has been added to a program, or if exercises have been added or removed. The delta (change) is not sent along with this object, so if the delta is important to your application, you can programmatically query the API to diff the saved state on your side to the new state.

Client accesses program for first time

This event is triggered when a client accesses a program for the first time. If groups of exercise programs have been added to an already existing program, then this event is also triggered the first time the client logs in to the program after a new exercise group has been added to it.

Client program has ended

Triggered either when a client's program is manually ended, or when the expiration date of a client's program was yesterday (the latter event is fired once every 24 hours). Adherence data for this program can be requested from the  appropriate API endpoint.

Message sent by client

A webhook is triggered when a client sends:

  • a standalone message using the chat window;
  • a pain alert (pain level of 10) for a specific exercise (in which case the feedback, if any, is included in the message object);
  • feedback related to a specific exercise.
  "message_id": "12345678997",
  "sender_type": "client",
  "sender_email": "null",
  "timestamp": "1789456789",
  "pain_level": "6",
  "exercise_name": "Squats",
  "exercise_id": "123456",
  "access_code": "abcdabcd",
  "video_call": "false",
  "call_duration": null,
  "body": "This was quite painful."

Video call has ended

When a video call has been ended (either by the practitioner, or by the client), a message object is sent back. The timestamp key contains the start date and time (UNIX timestamp), and the call_duration is shown in seconds.

  "message_id": "2345678997",
  "sender_type": "system",
  "sender_email": "null",
  "timestamp": "1789456789",
  "pain_level": "null",
  "exercise_name": "null",
  "exercise_id": "null",
  "access_code": "null",
  "video_call": "true",
  "call_duration": "1234",
  "body": "null"

Data export has been requested

When a data export has been requested, such as, for example, a practitioner clicking on a "Copy messages to my EHR" button in a Physitrack iframe.

Retrieving event history

To retrieve specific events, simply  query the /events endpoint of the Physitrack API.