OSPRY Docs

API reference (v1)

Webhooks

visitorIdentifiedV2

Webhook visitor.identified (POST): The opt-in v2 outbound webhook body.

Sent to the customer endpoint configured on an integration whose payload_version selects v2. Signed with X-Sight-Signature over the exact bytes, keyed for idempotency on X-Sight-Idempotency-Key.

Request body (application/json, required)

Fields:

  • classification (string): Omitted when empty. The velocity-rule label.
  • contract_version (const "2026-09-04", required)
  • emitted_at (string, required)
  • event (const "visitor.identified", required)
  • field_policy (FieldPolicy): The per-delivery accounting of what the caller received and what it did not. permitted_tiers is what the tenant may enable; enabled_tiers is what this integration has on.
    • enabled_tiers (array of enum 1, 2, 3, required)
    • included (integer, required)
    • missing (integer, required)
    • missing_reason (object, required): A count per reason. Every key is one of the five closed reasons.
    • permitted_tiers (array of enum 1, 2, 3, required)
    • withheld_tiers (array of enum "contact_handles", "sensitive_traits", required)
  • id (string, required): The visit_event id, and the X-Sight-Idempotency-Key value.
  • is_repeat (boolean, required)
  • served_from (string): Omitted when empty. "cache" on a serve-local of a recognized return.
  • subject (Contact, required): The shared contact object. It is the webhook body's subject verbatim and the read contract's single-resource body. Every key of a caller's key set K appears exactly once, either here as a value or in missing as a reason, never both and never neither.
    • company (object, required): The firmographic fields.
    • contract_version (const "2026-09-04", required): The dated contract version.
    • custom_fields (array of object, required): The tenant's own custom fields. Tier 1, always present (parent OD-27).
    • handles (object, required): Email and phone handles. emails[] and phones[] are tier 2.
    • id (string, required): The tenant-scoped identifier of the resolved person record.
    • identity (object, required): The subject identity fields.
    • links (object, required): Absolute links to this subject.
    • location (object, required): The subject location fields.
    • missing (object, required): Every key in this caller's key set K that carries no value, mapped to one of the five closed reasons.
    • object (const "contact", required): Always the literal "contact".
    • provenance (object, required): How this subject was resolved and when it was seen.
    • subject_type (enum "company_profile", "contact", "person_profile", required): Which catalogued subject this object describes.
    • traits (array of object, required): Tier 3 (sensitive_traits): the household, demographic and financial traits. The tier is available to every account and is off by default on each connector, so this array carries values only once the customer enables it on that connector. Until then it is empty and every tier-3 key is named in missing with the reason withheld_tier.
  • tier (enum "company", "person", required)
  • visit (object): The visit that produced this event.
    • captured_url (string | null)
    • domain_id (string | null)
    • referrer (string | null)
    • seen_at (string | null)
    • visitor_id (string | null)

Responses

  • Response 200: The receiver accepted the delivery.