Setting Up Signal

Setting up Particle Signal involves a few key steps to ensure you seamlessly receive and utilize real-time patient insights. This guide will walk you through configuring your systems to integrate with Signal's powerful capabilities.

Prerequisites

Before you begin, ensure you have:

• Particle Platform Access: An active Particle Health account with appropriate API keys for authentication. If you need to set this up, please refer to our Authentication Guide.
• Understanding of Webhooks: Familiarity with how webhooks work and the ability to develop and manage a reliable callback endpoint on your end.
• Contract for Particle Signal: Your organization must be contracted with Particle Health for the Signal solution. If you're unsure, please contact your Particle representative.

Step-by-Step Setup Guide

Follow these steps to configure your environment for receiving Signal alerts:

1. Configure Your Callback Endpoint

Signal delivers alerts to your systems via webhooks. To seamlessly receive these real-time notifications, you will need to develop and host a secure, publicly accessible callback endpoint on your server. This endpoint is where Particle will send POST requests containing your Signal alerts.

• How Webhooks Work: When a Signal alert is triggered, Particle's system will make an HTTP(S) POST request to the specific URL you provide. Your endpoint must be designed to receive, process, and acknowledge these requests.

• Registering Your Endpoint with Particle:

  Once your webhook endpoint is developed and hosted, you must provide its URL to Particle for configuration. Please contact your Particle Health representative or support team to register this URL in our system for your organization.

• Important Security Note & Implementation Details: All webhook notifications from Particle are signed. We highly recommend verifying the signature on every incoming request to ensure the notification genuinely originated from Particle and has not been tampered with. For detailed instructions on how to implement your webhook listener, including parsing payloads, handling HTTP responses, and performing signature verification, please refer to our comprehensive Webhook Event Notifications Guide.

2. Patient Registration

Before you can receive Signal alerts for a patient, they must be registered within the Particle Health platform. This establishes a unique particle_patient_id for each individual, which is essential for all subsequent actions.

• How to Register Patients:

  Patients are typically registered via the Patients API. This API allows you to create or update patient records within Particle Health.

  • Example Patients API Call (Create Patient):

    Bash

    curl -X POST "https://api.particlehealth.com/v1/patients" \
         -H "Authorization: Bearer YOUR_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{
               "first_name": "Jane",
               "last_name": "Doe",
               "date_of_birth": "1980-01-15",
               "gender": "female",
               "address": {
                 "address_line_1": "123 Main St",
                 "city": "Anytown",
                 "state": "IL",
                 "zip": "60601"
               }
             }'

  • Note: The particle_patient_id returned in the response from this API call is crucial for the next step.

3. Patient Subscription to Signal

Once patients are registered, you need to explicitly subscribe them to Particle Signal to start monitoring their activity and receiving alerts.

• Subscription Methods:

  • Organization-Wide Subscription: For organizations that wish to monitor all their registered patients, Particle can enable Signal at an organizational level. Please contact your Particle representative to discuss this option.

  • Cohort Subscription (via Subscriptions API): You can subscribe a specific group or "cohort" of patients using the Subscriptions API. This is ideal for managing specific patient populations.

    Bash

    curl -X POST "https://api.particlehealth.com/v1/subscriptions" \
         -H "Authorization: Bearer YOUR_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{
      "subscriptions": [
        {
          "particle_patient_id": "123456",
          "type": "MONITORING"
        },
        {
          "particle_patient_id": "78910",
          "type": "MONITORING"
        }
      ]
    }'

  • Individual Patient Subscription (via Subscriptions API): You can also subscribe individual patients as needed using the same Subscriptions API.

    Bash

    curl -X POST "https://api.particlehealth.com/v1/subscriptions" \
         -H "Authorization: Bearer YOUR_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{
      "subscriptions": [
        {
          "particle_patient_id": "123456",
          "type": "MONITORING"
        }
      ]
    }'

⏰

Note: It may take up to 24-48 hours for the initial monitoring to identify relevant historical context across the HINs, after which new events will trigger alerts.

4. Optional: Register Referral Organizations (for Referral Alerts)

If you plan to utilize Referral Alerts to track patient referrals to and from specific organizations, you'll need to register those organizations with Particle.

• Purpose: This allows Particle to monitor for referral documents involving these specific organizations within the network.
• How to Register Referral Organizations: You register organizations using the Referral Organizations API. First, you can retrieve a list of all supported organizations and their OIDs by calling the GET /referrals/organizations endpoint. Once you have the OID(s) for the organizations you wish to monitor, send a POST request to the following endpoint: For more details on managing referral organizations, refer to the Referral Management API documentation.

  • Request:

  • POST https://api.particlehealth.com/api/v1/referrals/organizations/registered

  • Example Payload:

    JSON

    {
      "organizations": [
        {
          "oid": "2.16.840.1.113883.3.8391.5.710576"
        }
      ]
    }

Testing in Sandbox Environment

We highly recommend testing your Signal integration in our sandbox environment before going live. This allows you to simulate alerts and verify your webhook setup without affecting production data.

• For detailed instructions on how to test Signal alerts and retrieve synthetic data, please refer to our Testing Signal in Sandbox guide.

Common Setup Issues & Troubleshooting

• Not Receiving Alerts?
  • Verify your callback endpoint is publicly accessible and correctly configured with Particle.
  • Check your server logs for any incoming requests from particlehealth.com that might be failing (e.g., HTTP 4xx or 5xx errors).
  • Ensure your patients are correctly registered and subscribed to Signal.
  • Confirm your API key is valid and has the necessary permissions.
• Webhook Signature Verification Failing?
  • Double-check your secret key used for HMAC verification.
  • Ensure you are using the correct hashing algorithm and encoding.
  • Refer to the Webhook Event Notifications Guide for exact implementation details.
• Missing Specific Alert Types?
  • Verify the patient is subscribed for the relevant alert types (e.g., Referral Alerts require registered referral organizations; ensure your project has specific alert features enabled by Particle).
  • Allow sufficient time for initial data processing, especially for network-derived alerts.