Technical Reference

Pingslap Payload Reference

The authoritative specification for incoming webhook payloads, supported root fields, structured objects, phone actions, trusted action links, and payload limits.

Data tiers at a glance

PINGSLAP processes incoming payload data across four distinct tiers:

Arbitrary data: Any unrecognized root-level fields are automatically displayed under Other Details.
Structured data: Recognized lead and tracking objects are organized into dedicated, formatted UI sections.
Phone data: Valid telephone formats anywhere in the payload receive an automated Call button.
Trusted actions: Explicit _pingslap.action objects render an Open URL button when Action Links are enabled.

Standard root fields

These top-level keys control the primary presentation of your alert.

Field	Type	Limit	Description
`title`	String	80 chars	Primary alert heading displayed prominently in notifications and feed. Truncated if exceeded.
`body`	String	4,000 chars	Main notification message text. Truncated if exceeded. Interchangeable with `message`.
`message`	String	4,000 chars	Alias for `body`. Truncated if exceeded.
`summary`	String	—	Optional short summary providing immediate secondary context.
`category`	String	—	Optional classification tag or workflow label (e.g., `Billing`, `DevOps`).
`priority`	String	—	Optional priority indicator (e.g., `urgent`, `high`, `normal`, `low`).

{
  "title": "Server Alert",
  "message": "High memory consumption detected on worker-04.",
  "summary": "Worker node approaching 95% threshold",
  "category": "Infrastructure",
  "priority": "high"
}

Structured lead object (`lead`)

Placing customer and prospect information inside a "lead": { ... } object causes PINGSLAP to organize those values into a dedicated Lead section.

Field	Aliases	Type	Description
`name`	—	String	Full customer or contact name.
`phone`	—	String	Contact telephone number. Recognized phone formats receive a one-tap Call button.
`email`	—	String	Customer email address. Displayed as selectable text for copying (not an interactive email action).
`city`	—	String	City or locality name.
`state`	—	String	State, province, or region.
`service`	—	String	Requested service or job scope (e.g., `Roof Replacement`).
`property_type`	`propertyType`	String	Classification of property (e.g., `Residential`, `Commercial`).
`roof_type`	`roofType`	String	Specific roof material or type (e.g., `Shingle`, `Metal`, `Tile`).
`lead_source`	`leadSource`	String	Channel or form where the inquiry originated.
`urgency`	—	String	Reported urgency timeline (e.g., `Emergency`, `High`, `Flexible`).

{
  "title": "New Roofing Lead",
  "lead": {
    "name": "Jane Doe",
    "phone": "(813) 555-9876",
    "email": "jane@example.com",
    "city": "Tampa",
    "state": "FL",
    "service": "Roof Replacement",
    "property_type": "Residential",
    "roof_type": "Tile",
    "lead_source": "Website Form",
    "urgency": "High"
  }
}

Note on unknown keys: Unknown or arbitrary keys nested inside the lead object should NOT be relied upon for display. If you have custom metadata, place it at the payload root so it appears under Other Details.

Structured tracking object (`tracking`)

Nesting marketing attribution fields inside "tracking": { ... } organizes campaign and analytics data into a dedicated Tracking section.

Field	Aliases	Type	Description
`campaign`	—	String	Campaign or promotion name.
`landing_page`	`landingPage`	String	Landing page URL. Displayed as selectable text; not an interactive action link.
`utm_source`	`utmSource`	String	Traffic source (e.g., `google`, `mailer`).
`utm_medium`	`utmMedium`	String	Marketing medium (e.g., `cpc`, `organic`).
`utm_campaign`	`utmCampaign`	String	UTM campaign identifier.
`referrer`	—	String	Referring website or URL.
`submitted_at`	`submittedAt`	String	Submission timestamp (ISO 8601 string recommended).

{
  "title": "New Campaign Lead",
  "tracking": {
    "campaign": "Fall Roofing Mailer",
    "landing_page": "https://example.com/roof",
    "utm_source": "mailer",
    "utm_medium": "print",
    "utm_campaign": "fall2026",
    "referrer": "https://direct.example.com",
    "submitted_at": "2026-09-18T18:00:00Z"
  }
}

URL display: URLs inside tracking remain inert display data. They do not automatically convert into clickable action buttons.

Arbitrary fields (Other Details)

PINGSLAP is designed to be flexible with the data you already send. Any root-level fields not recognized as standard or structured objects automatically render in an Other Details section:

Key names are formatted into readable labels.
Null, undefined, or empty string values may be suppressed from display.
Nested arbitrary objects and arrays are formatted and displayed as readable data.
Do not hide custom fields inside lead; place them at the root level so they are guaranteed to appear under Other Details.

{
  "title": "Order Shipped",
  "body": "Package has left the fulfillment center.",
  "order_id": "ORD-99281",
  "carrier": "FedEx",
  "tracking_number": "9205590164917312345678",
  "items": ["Roof Sealant 5gal", "Flashing 10ft"]
}

Phone numbers & Call action

PINGSLAP automatically detects recognized telephone numbers and attaches an interactive, one-tap Call button on iPhone.

No Lead wrapper required: Works both inside lead.phone and for root fields such as contact_number, phone, phone_number, or mobile.
Supported formats: Standard telephone formats including (813) 555-9876, 813-555-9876, and international +1 813 555 9876.
Arbitrary numbers: Plain numbers or digit sequences that do not match standard phone patterns will display as ordinary text without a Call button.

{
  "title": "Urgent Dispatch",
  "body": "Technician requested on site.",
  "contact_number": "(813) 555-9876"
}

Actionable content v1 (`_pingslap`)

Ordinary URLs in webhook payloads remain inert text. To provide an interactive button that opens an external destination, send a canonical _pingslap.action object.

{
  "title": "New CRM Lead",
  "lead": {
    "name": "Jane Doe",
    "phone": "(813) 555-9876"
  },
  "_pingslap": {
    "v": 1,
    "action": {
      "type": "url",
      "label": "Open Lead",
      "url": "https://crm.example.com/leads/8492"
    }
  }
}

Property	Type	Rules & Limits
`_pingslap.v`	Integer	Must be `1`.
`action.type`	String	Must be `"url"`. Canonical contract value.
`action.label`	String	Custom button text. Maximum 32 characters.
`action.url`	String	Must use `https://` only. Maximum 2,048 characters.

Security and delivery rules:

Space permission: The receiving Space must have Allow Action Links enabled in Space Settings. If disabled, the alert is delivered normally but the action button is omitted.
Destination verification: PINGSLAP shows the destination URL for user review before opening it in the browser or CRM application.
HTTPS enforcement: Insecure http:// URLs are rejected for actions.
Graceful degradation: Malformed, oversized, or unsupported action metadata will never cause webhook delivery to fail; the alert is still delivered cleanly without the button.
Single action: Exactly one action is supported per payload in v1.

Payload limits & truncation

PINGSLAP enforces system limits to ensure reliable delivery and consistent mobile rendering.

Constraint	Maximum Limit	Behavior if Exceeded
HTTP Request Body	1 MB	Request rejected with HTTP 413.
Stored Payload	32 KB	Internal payload storage capped.
Title (`title`)	80 characters	Truncated gracefully to 80 characters; alert still delivered.
Body (`body` / `message`)	4,000 characters	Truncated gracefully to 4,000 characters; alert still delivered.
Action URL (`action.url`)	2,048 characters	Action button omitted if exceeded; alert still delivered.
Action Label (`action.label`)	32 characters	Truncated to 32 characters.

Plain-language truncation: Rather than rejecting alerts because a title or message is too long, PINGSLAP trims the excess characters and delivers the notification. Your alerts will not fail silently due to long descriptions.

Supported content types

Webhook endpoints accept requests using standard POST bodies:

application/json (recommended): Full structured support for root fields, nested objects (lead, tracking), and _pingslap actions.
application/x-www-form-urlencoded: Standard web form submissions. Form keys are mapped to payload fields.

Developer Details & inspection

PINGSLAP includes a dedicated Developer Details view inside each alert in the iOS app. This area allows you to inspect:

The exact raw JSON payload received by the server.
Delivery timestamp and unique alert ID.
Space identifier and integration metadata.

Use Developer Details during integration to confirm your field names match PINGSLAP's recognized contract.

← Back to Payloads Guide Verify Integration →