Inbound Webhooks

Overview Outbound Webhooks Inbound Webhooks Status Lifecycle Case Configuration Testing & Sandbox Onboarding Checklist

Your system → PayMe

Send us status updates as you process leads. Each update keeps the user engaged in the PayMe app and helps our system find you better leads over time.

Why status updates matter

Keep leads warm. Every update triggers a push notification. Users respond faster to document requests, sign retainers sooner, and are less likely to go cold.

Improve lead quality. Your outcome data trains our qualification engine. The more we know about which leads convert, the better leads we send you. It's a feedback loop that gets stronger over time.

Reduce drop-off. Users who see their case progressing in-app stay engaged with the process. No more leads going dark because they forgot they applied.

Endpoint

POST https://api.payme.dev/api/webhooks/partner-status?access_token=YOUR_TOKEN

Your access token is provided during onboarding. It authenticates your requests and identifies your partner account.

Standard payload format

If you can send our standard format, zero custom work is needed on either side. Just POST JSON to the endpoint above.

json

{
  "LeadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Status": "RetainerSigned",
  "Message": "Client signed retainer agreement on 2026-03-04",
  "ExternalLeadId": "your-internal-id-456",
  "CaseCode": "RU",
  "ContactPhone": "5551234567",
  "ContactEmail": "jane.doe@example.com",
  "LawFirm": "Smith Law Group"
}

Field reference

Field	Type	Required	Description
`LeadId`	string	Yes	The UUID we sent in the outbound webhook. Use this to identify the lead.
`Status`	string	Yes	Your status string (e.g. "RetainerSigned"). We map it to our canonical statuses.
`Message`	string	No	Free-text context about the status change.
`ExternalLeadId`	string	Recommended	Your internal ID for this lead. Helps us match if LeadId is unavailable.
`CaseCode`	string	No	Case/campaign identifier (e.g. "RU-SMITHLAW").
`ContactPhone`	string	Recommended	Lead's phone number. Used for matching if LeadId is unavailable.
`ContactEmail`	string	No	Lead's email address. Secondary matching fallback.
`ContactName`	string	No	Lead's full name. Last-resort matching fallback.
`LawFirm`	string	No	Law firm handling this lead, if different from your organization.

Already have your own webhook format?

You don't need to change anything. If your system already sends webhooks in a different structure, we build a custom adapter that maps your fields to ours. Zero work on your end.

Just send us a sample payload during onboarding and we'll handle the translation. We already support partners with:

Nested contact info objects
Alternative field names (e.g. LeadStatus instead of Status)
Custom internal ID formats
Composite status fields (status + sub-status)

Example request

bash

curl -X POST \
  'https://api.payme.dev/api/webhooks/partner-status?access_token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "LeadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "Status": "RetainerSigned",
    "ExternalLeadId": "your-internal-id-456"
  }'

Response codes

Code	Meaning	What to do
`200`	Success	Lead matched, status recorded.
`400`	Bad Request	Missing LeadId after normalization. Check your payload.
`401`	Unauthorized	Invalid or missing access_token.
`404`	Not Found	LeadId not matched to any lead. Verify you're using the UUID we sent.
`500`	Server Error	Our problem. Retry with exponential backoff.

Lead matching

We automatically match your webhook to the right user. The best way to guarantee a match is to include the LeadId UUID from the outbound webhook.

UUIDLeadId matches the UUID we sent (fastest, preferred)

External IDYour ExternalLeadId matches a previously stored partner ID

PhoneLast 10 digits of ContactPhone

EmailCase-insensitive ContactEmail match

NameContactName match (last resort, higher collision risk)

Best practice: Always return the LeadId UUID we included in the outbound webhook. This guarantees a direct match with zero ambiguity.