Matter webhooks

https://app.superpractice.com/api/webhooks/matters/{webhook_token}

Overview

Matter webhooks let another system post matter data to Superpractice over HTTPS. A successful webhook can create or update a matter, match or create the related contact, mark the matter stage, and create one or more line items tied to your Superpractice services.

The endpoint is best for retained-matter events from intake software, middleware, custom forms, spreadsheets, or internal systems that are not covered by the HubSpot or GoHighLevel integrations.

Setup

1. Open Settings > Integrations in Superpractice.
2. Create a Matter Webhook endpoint.
3. Copy the endpoint URL. Treat the URL as a secret because the token in the path authenticates the sender.
4. Click Start Test, send a sample webhook, then use the captured payload to map fields.
5. Save field mappings, matter stage rules, and line item mappings.
6. Send a live webhook and confirm the matter, contact, and line items in Superpractice.

Request basics

Send an HTTPS POST request with a JSON body and the Content-Type: application/json header.

curl -X POST "https://app.superpractice.com/api/webhooks/matters/{webhook_token}" \
  -H "Content-Type: application/json" \
  --data '{
    "sourceSystem": "external_system",
    "externalMatterId": "matter_example_001",
    "stage": "retained",
    "amount": "5000.00",
    "contact": {
      "fullName": "Example Contact",
      "email": "contact@example.com",
      "phone": "+15550100000"
    },
    "lineItems": [
      {
        "serviceValue": "service_identifier",
        "price": "5000.00",
        "quantity": 1
      }
    ]
  }'

The default rate limit is 120 requests per hour per endpoint. The endpoint returns JSON for success and errors.

You can send a GET request to the same URL to verify that the endpoint token is active. Live matter creation only happens on POST.

Required fields

Contact matching

Superpractice looks for an existing contact before creating a new one. Matching uses the external contact ID for the source system when available, then phone, then email.

You can send contact.fullName instead of separate first and last names. Superpractice splits common full-name formats, including middle initials, middle names, prefixes, suffixes, and comma-separated names. If first and last name fields are also mapped, those fields take priority over the split full name.

Matter stages

There are three supported ways to set the matter stage.

• Fixed stage: choose an "Always use" stage in Superpractice. The webhook does not need to send stage or status.
• Exact Superpractice stage: send one of new, qualified, engagement_letter_sent, retained, or lost.
• External status: send your own value, such as completed or accepted, then add a translation row in the Matter Stage section.

Dates, amounts, and fee types

Date-only values like 2026-05-14, short values like 26-05-14, and spreadsheet serial dates are also accepted. ISO date/time is the safest format because it preserves timezone intent.

Services and line items

Line items are how retained matters connect to your Superpractice services and reporting. The recommended format is an array named lineItems. Each line item should include a service value, price, and quantity.

Use lineItems[].serviceValue to send the webhook service value shown in Settings > Services. If the sender uses different names or codes, map those incoming values in Settings > Integrations.

When an existing matter is updated by the same sourceSystem and externalMatterId, Superpractice replaces the webhook-created line items for that matter with the latest payload.

Minimal payload

{
  "sourceSystem": "external_system",
  "externalMatterId": "matter_example_001",
  "stage": "retained",
  "amount": "5000.00",
  "feeType": "flat_fee",
  "contact": {
    "fullName": "Example Contact",
    "email": "contact@example.com",
    "phone": "+15550100000"
  }
}

Multiple line items

{
  "sourceSystem": "external_system",
  "externalMatterId": "matter_example_002",
  "stage": "retained",
  "createdAt": "2026-05-14T13:45:00Z",
  "closeDate": "2026-05-14T14:00:00Z",
  "contact": {
    "externalContactId": "contact_example_001",
    "fullName": "Example Contact",
    "email": "contact@example.com",
    "phone": "+15550100000"
  },
  "lineItems": [
    {
      "externalLineItemId": "line_item_example_001",
      "serviceValue": "service_identifier_a",
      "name": "Imported line item A",
      "price": "3000.00",
      "quantity": 1
    },
    {
      "externalLineItemId": "line_item_example_002",
      "serviceValue": "service_identifier_b",
      "name": "Imported line item B",
      "price": "$2,000.00",
      "quantity": 1
    }
  ]
}

Custom payloads

The sender does not have to match Superpractice field names. Use Start Test to capture the real payload, then map each incoming field to a Superpractice field.

{
  "id": "matter_example_003",
  "contactInfo": {
    "name": "Example Contact",
    "email": "contact@example.com",
    "phone": "+15550100000"
  },
  "package": "service_identifier_a",
  "total": "$5,000.00",
  "completed_at": "2026-05-14T14:00:00Z"
}

In this example, map id to External Matter ID, contactInfo.name to Full Name, package to Service / Package Field, and total to Matter Amount.

Responses

A successful request returns the action taken and the Superpractice IDs that were created or updated.

{
  "success": true,
  "action": "created",
  "contactId": "00000000-0000-0000-0000-000000000000",
  "matterId": "00000000-0000-0000-0000-000000000000",
  "stage": "retained",
  "value": "5000.00",
  "warnings": []
}

Common error responses:

• 400 invalid JSON or missing required payload shape.
• 401 invalid or inactive webhook token.
• 422 invalid status, fee type, or missing stage/service mapping.
• 429 endpoint rate limit exceeded.

Testing

1. In Superpractice, open the Matter Webhook configuration.
2. Click Start Test.
3. Send one webhook from the source system.
4. Select the captured payload in Superpractice and confirm the example fields look correct.
5. Map required contact and matter fields.
6. Save mappings, then send another webhook with a unique External Matter ID to create a live test matter.

You can capture multiple test payloads and switch between them when mapping fields. This is useful when the sender has different payload shapes for single-service and multi-line-item matters.

Troubleshooting

The webhook created duplicate matters

Make sure the sender reuses the same externalMatterId for the same matter. A new ID creates a new matter.

The contact did not match

Send a stable external contact ID, normalized phone number, or email. Phone matching happens before email matching.

The service is missing from a line item

Use the webhook value from Settings > Services, or add a service-value mapping in Settings > Integrations. The webhook may still create the line item, but reporting quality is better when every line item maps to a service.

The stage was rejected

Use an exact Superpractice stage, choose a fixed stage, or add a translation row for the sender's status value.

FAQ

Do I need to rotate the token when moving from test to production?

No. The token is the important part of the endpoint. Use the production domain with the same token, or rotate only if you want to invalidate the old URL.

Can one matter have multiple line items?

Yes. Send lineItems as an array. Each item can map to a different Superpractice service.

Can I hard-code the stage or fee type?

Yes. For fields with fixed choices, you can choose an "Always use" value in the mapping selector instead of mapping a payload field.

Can I send custom fields?

Yes. Send a customFields object in the canonical payload. Superpractice stores those values on the matter.