Event catalog
Every webhook event type, when it fires, and a full example payload for each.
Every event uses the same envelope. data.referral is the referral object without the patient block. Patient personal data is never sent in webhooks.
The examples below follow one live referral, RHB-4829173655, from creation to completion, followed by three other outcomes. Its data.sequence goes up by 1 with each event. IDs and timestamps are illustrative.
| Type | When it fires | data.previous_status |
|---|---|---|
referral.created | A referral is created (API, referral-link lead, or portal) | null |
referral.contacted | Patient reached / intake started (incl. patient messaged Joy with the tracking code) | Usually received |
referral.provider_matched | A physiotherapist was assigned | The current status (matching doesn't change it) |
referral.booked | First appointment confirmed (payment verified or care covered) | Usually contacted |
referral.in_treatment | Treatment under way | Usually booked |
referral.completed | Care episode completed | Usually in_treatment |
referral.not_suitable | Not appropriate for Rehabify services | The status before the change |
referral.cancelled | Cancelled / refunded | The status before the change |
referral.closed | Closed | The status before the change |
ping | Test event from the portal or POST /sandbox/trigger-webhook | Not present |
referral.created
Fires as soon as a referral is created, whether through the API, a referral-link lead or the Partner Portal. previous_status is null.
{
"id": "evt_01JA4S0A1B2C3D4E5F6G7H8J9K",
"object": "event",
"type": "referral.created",
"api_version": "2026-10-01",
"created_at": "2026-10-13T09:30:00.000Z",
"environment": "live",
"data": {
"previous_status": null,
"sequence": 1,
"referral": {
"object": "referral",
"id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
"tracking_code": "RHB-4829173655",
"partner_reference": "HMO-REF-2026-0091",
"environment": "live",
"status": "received",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Okafor"
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "hmo_direct_billing",
"provider": null,
"sessions": { "completed": 0, "total": 6, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
},
"metadata": { "member_plan": "gold" },
"created_at": "2026-10-13T09:30:00.000Z",
"updated_at": "2026-10-13T09:30:00.000Z"
}
}
}referral.contacted
Fires when Rehabify's care team or Joy reaches the patient and intake starts. This includes when the patient messages Joy on WhatsApp with the tracking code, for example through links.whatsapp_intake_url.
{
"id": "evt_01JA4S9M2N3P4Q5R6S7T8V9W0X",
"object": "event",
"type": "referral.contacted",
"api_version": "2026-10-01",
"created_at": "2026-10-13T09:32:40.000Z",
"environment": "live",
"data": {
"previous_status": "received",
"sequence": 2,
"referral": {
"object": "referral",
"id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
"tracking_code": "RHB-4829173655",
"partner_reference": "HMO-REF-2026-0091",
"environment": "live",
"status": "contacted",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Okafor"
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "hmo_direct_billing",
"provider": null,
"sessions": { "completed": 0, "total": 6, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
},
"metadata": { "member_plan": "gold" },
"created_at": "2026-10-13T09:30:00.000Z",
"updated_at": "2026-10-13T09:32:40.000Z"
}
}
}referral.provider_matched
Fires when a physiotherapist is assigned. Matching doesn't change the status, so previous_status equals the referral's current status. referral.provider now holds the physiotherapist's name and license_number. In sandbox, it's { "name": "Sandbox Physiotherapist", "license_number": "SANDBOX-0001" }.
{
"id": "evt_01JA4SXK3L4M5N6P7Q8R9S0T1V",
"object": "event",
"type": "referral.provider_matched",
"api_version": "2026-10-01",
"created_at": "2026-10-13T09:34:05.000Z",
"environment": "live",
"data": {
"previous_status": "contacted",
"sequence": 3,
"referral": {
"object": "referral",
"id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
"tracking_code": "RHB-4829173655",
"partner_reference": "HMO-REF-2026-0091",
"environment": "live",
"status": "contacted",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Okafor"
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "hmo_direct_billing",
"provider": { "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" },
"sessions": { "completed": 0, "total": 6, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
},
"metadata": { "member_plan": "gold" },
"created_at": "2026-10-13T09:30:00.000Z",
"updated_at": "2026-10-13T09:34:05.000Z"
}
}
}referral.booked
Fires when the first appointment is confirmed: the payment has been verified, or the care is covered (for example, by HMO direct billing). If no physiotherapist had been matched yet, referral.provider_matched fires first.
{
"id": "evt_01JA4T7Q9Y2V3W4X5Z6A7B8C9D",
"object": "event",
"type": "referral.booked",
"api_version": "2026-10-01",
"created_at": "2026-10-13T09:35:12.000Z",
"environment": "live",
"data": {
"previous_status": "contacted",
"sequence": 4,
"referral": {
"object": "referral",
"id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
"tracking_code": "RHB-4829173655",
"partner_reference": "HMO-REF-2026-0091",
"environment": "live",
"status": "booked",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Okafor"
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "hmo_direct_billing",
"provider": { "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" },
"sessions": { "completed": 0, "total": 6, "last_session_at": null, "next_session_at": "2026-10-15T10:00:00.000Z" },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
},
"metadata": { "member_plan": "gold" },
"created_at": "2026-10-13T09:30:00.000Z",
"updated_at": "2026-10-13T09:35:12.000Z"
}
}
}referral.in_treatment
Fires when rehabilitation sessions are under way.
{
"id": "evt_01JAA2B3C4D5E6F7G8H9J0K1M2",
"object": "event",
"type": "referral.in_treatment",
"api_version": "2026-10-01",
"created_at": "2026-10-15T10:45:00.000Z",
"environment": "live",
"data": {
"previous_status": "booked",
"sequence": 5,
"referral": {
"object": "referral",
"id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
"tracking_code": "RHB-4829173655",
"partner_reference": "HMO-REF-2026-0091",
"environment": "live",
"status": "in_treatment",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Okafor"
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "hmo_direct_billing",
"provider": { "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" },
"sessions": {
"completed": 1,
"total": 6,
"last_session_at": "2026-10-15T10:00:00.000Z",
"next_session_at": "2026-10-18T10:00:00.000Z"
},
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
},
"metadata": { "member_plan": "gold" },
"created_at": "2026-10-13T09:30:00.000Z",
"updated_at": "2026-10-15T10:45:00.000Z"
}
}
}referral.completed
Fires when the care episode is complete and the patient has been discharged. A good moment to download the progress report PDF.
{
"id": "evt_01JC7N8P9Q0R1S2T3V4W5X6Y7Z",
"object": "event",
"type": "referral.completed",
"api_version": "2026-10-01",
"created_at": "2026-11-05T11:00:00.000Z",
"environment": "live",
"data": {
"previous_status": "in_treatment",
"sequence": 6,
"referral": {
"object": "referral",
"id": "jd7f3k2m9x1q8w4e5r6t7y8u9i0o1p2a",
"tracking_code": "RHB-4829173655",
"partner_reference": "HMO-REF-2026-0091",
"environment": "live",
"status": "completed",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Okafor"
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "hmo_direct_billing",
"provider": { "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" },
"sessions": {
"completed": 6,
"total": 6,
"last_session_at": "2026-11-05T10:00:00.000Z",
"next_session_at": null
},
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-4829173655",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-4829173655"
},
"metadata": { "member_plan": "gold" },
"created_at": "2026-10-13T09:30:00.000Z",
"updated_at": "2026-11-05T11:00:00.000Z"
}
}
}referral.not_suitable
Fires when Rehabify's services aren't appropriate for the patient. The patient is redirected to appropriate care. No clinical detail is disclosed.
{
"id": "evt_01JA6D2E3F4G5H6J7K8M9N0P1Q",
"object": "event",
"type": "referral.not_suitable",
"api_version": "2026-10-01",
"created_at": "2026-10-14T11:20:00.000Z",
"environment": "live",
"data": {
"previous_status": "contacted",
"sequence": 3,
"referral": {
"object": "referral",
"id": "jd7a1s2d3f4g5h6j7k8l9z0x1c2v3b4n",
"tracking_code": "RHB-5938204716",
"partner_reference": "HMO-REF-2026-0107",
"environment": "live",
"status": "not_suitable",
"clinical": {
"condition": "Knee pain",
"priority": "standard",
"recommended_sessions": 4,
"referring_clinician": null
},
"care": { "preferred_mode": "in_person", "preferred_contact_channel": "phone" },
"billing_mode": "hmo_direct_billing",
"provider": null,
"sessions": { "completed": 0, "total": 4, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-5938204716",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-5938204716"
},
"metadata": { "member_plan": "silver" },
"created_at": "2026-10-14T08:00:00.000Z",
"updated_at": "2026-10-14T11:20:00.000Z"
}
}
}referral.cancelled
Fires when the referral or its booking is cancelled or refunded. If a commission was recorded for the booking, it's reversed (see Commissions).
{
"id": "evt_01JA7F4G5H6J7K8M9N0P1Q2R3S",
"object": "event",
"type": "referral.cancelled",
"api_version": "2026-10-01",
"created_at": "2026-10-16T15:05:00.000Z",
"environment": "live",
"data": {
"previous_status": "booked",
"sequence": 5,
"referral": {
"object": "referral",
"id": "jd7q9w8e7r6t5y4u3i2o1p0a9s8d7f6g",
"tracking_code": "RHB-7120493861",
"partner_reference": "HMO-REF-2026-0112",
"environment": "live",
"status": "cancelled",
"clinical": {
"condition": "Shoulder stiffness",
"priority": "standard",
"recommended_sessions": 6,
"referring_clinician": "Dr. Bello"
},
"care": { "preferred_mode": "remote", "preferred_contact_channel": "whatsapp" },
"billing_mode": "patient_self_pay",
"provider": { "name": "Chiamaka Obi", "license_number": "MRTBN/PT/12345" },
"sessions": { "completed": 0, "total": 6, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-7120493861",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-7120493861"
},
"metadata": {},
"created_at": "2026-10-14T09:10:00.000Z",
"updated_at": "2026-10-16T15:05:00.000Z"
}
}
}referral.closed
Fires when no further activity is expected on the referral, for example after the patient doesn't proceed with care.
{
"id": "evt_01JAC8H9J0K1M2N3P4Q5R6S7T8",
"object": "event",
"type": "referral.closed",
"api_version": "2026-10-01",
"created_at": "2026-10-28T09:00:00.000Z",
"environment": "live",
"data": {
"previous_status": "contacted",
"sequence": 3,
"referral": {
"object": "referral",
"id": "jd7z8x7c6v5b4n3m2l1k0j9h8g7f6d5s",
"tracking_code": "RHB-3304817726",
"partner_reference": "HMO-REF-2026-0120",
"environment": "live",
"status": "closed",
"clinical": {
"condition": "Ankle sprain",
"priority": "standard",
"recommended_sessions": 4,
"referring_clinician": null
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "patient_self_pay",
"provider": null,
"sessions": { "completed": 0, "total": 4, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-3304817726",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-3304817726"
},
"metadata": {},
"created_at": "2026-10-14T13:45:00.000Z",
"updated_at": "2026-10-28T09:00:00.000Z"
}
}
}ping
A test event sent from the portal or with POST /sandbox/trigger-webhook. data contains a message and a referral. If you passed a sandbox referral_id, that's the referral used. Otherwise it's a sample referral with the id ref_sample_000000000000000000000000 and the tracking_code RHB-1234567890. A ping has no previous_status or sequence.
{
"id": "evt_01JA4V2K8M3N5P7Q9R1S3T5V7W",
"object": "event",
"type": "ping",
"api_version": "2026-10-01",
"created_at": "2026-10-13T10:00:00.000Z",
"environment": "sandbox",
"data": {
"message": "Test event from Rehabify",
"referral": {
"object": "referral",
"id": "ref_sample_000000000000000000000000",
"tracking_code": "RHB-1234567890",
"partner_reference": null,
"environment": "sandbox",
"status": "received",
"clinical": {
"condition": "Lower back pain",
"priority": "standard",
"recommended_sessions": 4,
"referring_clinician": null
},
"care": { "preferred_mode": "patient_choice", "preferred_contact_channel": "whatsapp" },
"billing_mode": "patient_self_pay",
"provider": null,
"sessions": { "completed": 0, "total": 4, "last_session_at": null, "next_session_at": null },
"links": {
"tracking_url": "https://physioaroundme.com/track/RHB-1234567890",
"whatsapp_intake_url": "https://wa.me/2348061525811?text=START%20RHB-1234567890"
},
"metadata": {},
"created_at": "2026-10-13T10:00:00.000Z",
"updated_at": "2026-10-13T10:00:00.000Z"
}
}
}Test events for other types
When you trigger any type other than ping from the portal or with POST /sandbox/trigger-webhook, the event has the normal envelope and is signed like a real one, but its data is marked as a test:
| Field | Value in a test event |
|---|---|
data.previous_status | null |
data.sequence | 0 |
data.test | true |
data.referral | The sandbox referral you named in referral_id, or the sample referral shown above |
Real events never include data.test. Test events don't change the referral, so you can ignore them in your ordering logic.