Skip to main content

Upsert Member Action

The Upsert Member action creates or updates a member when triggered by an incoming webhook or integration event. It is the primary action for integration-based onboarding flows — for example, automatically enrolling a patient when eClinicalWorks or Salesforce sends a webhook with their contact information.

How it fits together: "Upsert Member" is an Action type in Gravity Rail. It is triggered by events that carry an incoming member record (such as a webhook payload), and it writes that record to the workspace as a new or updated member.

When to Use​

  • Integration onboarding — Automatically enroll members when an external system (EHR, CRM, scheduling system) sends a webhook.
  • Record sync — Keep member data in sync by re-running the upsert whenever an external system updates a record.
  • Selective creation — Create members only if they don't yet exist (create_only with skipIfExists).
  • Selective updates — Update only members who are already enrolled (update_only).

Prerequisites​

  • An Event Rule configured to fire on an incoming webhook event
  • The webhook payload must include at least one identity field: external_id, email, or phone
  • The workspace must have the MEMBER_UPSERT_REQUEST capability enabled (included by default on webhook-triggered rules)

Parameters​

ParameterTypeDefaultDescription
behaviorenumupsertControls create/update logic. See values below.
skipIfExistsbooleanfalseWhen behavior is create_only: silently skip instead of failing when the member already exists.
skipIfNotFoundbooleanfalseWhen behavior is update_only: silently skip instead of failing when the member is not found.

behavior Values​

ValueWhat It Does
upsertCreate the member if they don't exist; update them if they do. (Default)
create_onlyOnly create new members. If the member already exists, the action fails unless skipIfExists is true.
update_onlyOnly update existing members. If the member is not found, the action fails unless skipIfNotFound is true.

Identity Lookup Order​

The action looks up existing members in this order:

  1. external_id — the identifier from your external system
  2. email
  3. phone

At least one of these must be present in the webhook payload for the action to run.

Setting Up the Action​

1. Create an Event Rule​

Go to Actions in your workspace and click New Action.

2. Set the Trigger​

Choose a trigger that carries incoming member data, such as Webhook Received on your configured webhook endpoint.

3. Select "Upsert Member" as the action type​

In the action type dropdown, select Upsert Member.

4. Configure behavior​

Choose the behavior that matches your use case:

  • upsert — Safe default. Works for both new members and updates.
  • create_only — Use when you only want to enroll new members and never overwrite existing records.
  • update_only — Use when members must already exist (e.g., syncing data after an initial enrollment step).

5. Configure skip flags (optional)​

  • Enable Skip if exists (skipIfExists) when using create_only to silently ignore duplicate webhooks instead of logging an error.
  • Enable Skip if not found (skipIfNotFound) when using update_only to silently ignore webhooks for members who haven't enrolled yet.

6. Save the action​

Click Save. The action will run whenever the trigger fires.

Worked Example: Automatic Patient Enrollment from a Webhook​

Goal: Automatically create a member when a scheduling system sends a new patient webhook. If the patient already exists, update their record.

Event Rule setup:

  • Trigger: Webhook Received (your scheduling system endpoint)
  • Action: Upsert Member
    • behavior: upsert
    • skipIfExists: false (not needed for upsert mode)

Webhook payload (sent by the scheduling system):

{
  "external_id": "PT-10042",
  "email": "placeholder@example.com",
  "first_name": "Alex",
  "last_name": "Sample",
  "phone": "+15550001234",
  "labels": ["new-patient"],
  "data": {
    "intake_form": {
      "preferred_language": "en",
      "appointment_type": "initial"
    }
  }
}

Replace placeholder values with your actual field names. Do not include real patient data in action configurations or test setups.

What happens:

  1. The scheduling system sends a webhook when the patient is scheduled.
  2. Gravity Rail fires the event rule.
  3. The Upsert Member action looks up PT-10042 in the workspace.
  4. If not found: creates a new member with the provided name, email, phone, label new-patient, and intake form data.
  5. If found: updates the existing member's fields with the incoming data.

Error Outcomes​

SituationbehaviorSkip flagResult
Member not foundupdate_onlyskipIfNotFound: falseAction fails, error logged
Member not foundupdate_onlyskipIfNotFound: trueAction skipped silently
Member already existscreate_onlyskipIfExists: falseAction fails, error logged
Member already existscreate_onlyskipIfExists: trueAction skipped silently
No identity field in payloadanyanyAction fails — webhook payload must include external_id, email, or phone

Tips​

  • Use upsert for most cases — It handles both creation and updates safely and is idempotent.
  • Prefer skipIfExists over create_only alone — Duplicate webhooks are common; skipIfExists: true prevents noisy errors in your action logs.
  • Check action logs — Failed actions show the error reason (e.g., member not found, missing identity fields) in the Actions log view.
  • Combine with CEL conditions — Use CEL conditions to filter which webhooks trigger the upsert (e.g., only process records of a specific type).