Webhook Callbacks

Overview

This documents the job.contact.scored webhook callback that TitanX sends to your configured endpoint when a contact completes scoring.

Related Documentation:

Webhooks Guide - Implementation guide with code examples
Webhook Management API - Endpoints to create and manage webhooks

Webhook Specification

POST job.contact.scored

TitanX sends this POST request to your configured webhook URL when a contact completes scoring.

Headers

string

required

HMAC-SHA256 signature (base64) of the request body for verification. Always verify this signature before processing the webhook.Example: jdoe+XYZ123abc/def456GHI789==

string

required

Always application/json

string

TitanX webhook user agentExample: TitanX-Webhooks/1.0

Request Body

object

required

An object containing the scored Contact.

Show payload properties

object

required

The complete scored Contact object with all available fields.

Show Contact Properties

string

Unique contact identifier (UUID)

string

User ID who owns this contact (UUID)

string

Job ID this contact belongs to (UUID)

string

Client ID (UUID)

string

required

Contact’s first name

string

required

Contact’s last name

object[]

required

Canonical phone representation for this contact. This supersedes the deprecated flat phone/phone2–phone5 fields (and their Status/Type/Country/Region variants) and is the recommended way to read phone data. Unlike the flat fields, this array also includes enrichment phones beyond the 5-number cap.

Show phone properties

string | null

The phone number (e.g., "+14155551001")

string | null

Propensity status for this number. Possible values: p1, p1 - h, p1 - ivr, p1 - dnc, p1 - sf, p2, p2 - h, p2 - ivr, p2 - sf, p3, p3 - h, p3 - ivr, p3 - sf, na, na - h, na - ivr, na - auth, na - dnc

string | null

Phone type. Standard values: mobile, direct, hq, other. Phones discovered via enrichment use the form TitanX Enriched Phone N (e.g., "TitanX Enriched Phone 1").

string | null

Country code for this number (e.g., "US")

string | null

Region for this number. Possible values: US, EMEA, APAC

integer

required

1-indexed ordinal position of this phone within the contact.

string | null

IVR navigation path for reaching this number, when available.

object | null

The single recommended number to dial for this contact — TitanX’s pick of the highest-propensity, most reachable number from phones[], surfaced so you don’t have to rank the array yourself. null when no suitable number is available.

Show bestPhone properties

string

required

The recommended phone number (e.g., "+14155551001")

string

required

string | null

IVR navigation path for reaching this number, when available.

string

required

Company name

string

Lead identifier

string

Email address

string

Job title (e.g., “Chief Technology Officer”, “VP of Sales”)

string

deprecated

Primary phone number. Deprecated — use the phones[] array instead.

enum

deprecated

Deprecated — use phones[].status. Primary phone status. Possible values: p1, p1 - h, p1 - ivr, p1 - dnc, p1 - sf, p2, p2 - h, p2 - ivr, p2 - sf, p3, p3 - h, p3 - ivr, p3 - sf, na, na - h, na - ivr, na - auth, na - dnc

enum

deprecated

Deprecated — use phones[].type. Primary phone type. Possible values: mobile, direct, hq, other

string

deprecated

Deprecated — use phones[].country. Primary phone country code (e.g., “US”)

string

deprecated

Second phone number. Deprecated — use the phones[] array instead.

enum

deprecated

Deprecated — use phones[].status. Second phone status (same values as phoneStatus)

enum

deprecated

Deprecated — use phones[].type. Second phone type (same values as phoneType)

string

deprecated

Deprecated — use phones[].country. Second phone country code

string

deprecated

Third phone number. Deprecated — use the phones[] array instead.

enum

deprecated

Deprecated — use phones[].status. Third phone status

enum

deprecated

Deprecated — use phones[].type. Third phone type

string

deprecated

Deprecated — use phones[].country. Third phone country code

string

deprecated

Fourth phone number. Deprecated — use the phones[] array instead.

enum

deprecated

Deprecated — use phones[].status. Fourth phone status

enum

deprecated

Deprecated — use phones[].type. Fourth phone type

string

deprecated

Deprecated — use phones[].country. Fourth phone country code

string

deprecated

Fifth phone number. Deprecated — use the phones[] array instead.

enum

deprecated

Deprecated — use phones[].status. Fifth phone status

enum

deprecated

Deprecated — use phones[].type. Fifth phone type

string

deprecated

Deprecated — use phones[].country. Fifth phone country code

string

Phone extension

string

Contact’s LinkedIn profile URL

string

Street address

string

City

string

State or province

string

ZIP or postal code

string

Country

string

Time zone (e.g., “America/Los_Angeles”)

string

Department (e.g., “Engineering”)

string

Seniority level (e.g., “C-Level”)

string

Job function or role (e.g., “Engineering”)

string

Contact persona

string

Company website URL

string

Company LinkedIn URL

string

Company street address

string

Company city (e.g., “San Francisco”)

string

Company state (e.g., “CA”)

string

Company ZIP code

string

Company country (e.g., “USA”)

string

Employee count range (e.g., “501-1000”)

string

Revenue range (e.g., “

50M-

100M”)

string

Industry category (e.g., “Technology”)

string

Sub-industry (e.g., “Software”)

string

SIC codes (e.g., “7372”)

string

NAICS codes (e.g., “511210”)

string

Technologies used (e.g., “AWS, React, Node.js”)

enum

Overall lead score based on highest phone score. Possible values: P1, P2, P3, Needs Attention, No Numbers Found, Uncontacted

string

Campaign list name (e.g., “Q1 2024 Campaign”)

string

Record owner (e.g., “sales@acme.com”)

string

Contact CRM identifier (e.g., “SF-12345”)

string

Account CRM identifier (e.g., “SF-ACC-678”)

string

Database contact ID

string

Database company ID

string

Customer contact identifier

string

Enrichment contact ID

string

Contact intent indicator (nullable)

object

Additional unmapped fields as key-value pairs

string

Timestamp when the contact was created (ISO 8601 format)Example: "2024-01-15T10:30:00Z"

string

Timestamp when the contact was last updated (ISO 8601 format)Example: "2024-01-15T10:35:00Z"

object

required

Context about the job that triggered this event.

Show job properties

string | null

The ID of the originating job (UUID). Use this to correlate the event back to a specific job. May be null for legacy events.

enum | null

The type of job that produced this event. Use this to route handling logic, as different job types annotate different fields. Possible values: scoring, enrichment, rescoring, score_enriched, enrich_rejected, enrich_final, titan_scoring, lightning_scoring, enrich_and_score, enrich_and_titan, enrich_score_rejected, enrich_titan_rejected. May be null for legacy events.

string

required

The type of webhook event. Always "job.contact.scored" for this callback.

number

required

Unix timestamp in milliseconds when the event occurred.Example: 1705318200000

string

required

API version for this webhook payload. Currently "v2".

string

required

Unique identifier for this webhook event (UUID format). Use this for idempotency to detect and skip duplicate deliveries.Example: "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"

Expected Response

Your webhook endpoint should return appropriate HTTP status codes:

Status Code	Description
`200-299`	Success - webhook processed, no retry
`400-499`	Client error - no retry (except 408, 429)
`408`	Request timeout - will retry
`429`	Rate limited - will retry
`500-599`	Server error - will retry

Retry Policy

Failed deliveries are retried with exponential backoff for up to 3 days.

Security Requirements

Signature Verification

All webhook requests include an X-TitanX-Signature header with an HMAC-SHA256 signature. Algorithm: Base64(HMAC-SHA256(webhook_secret, request_body))

Always verify the signature before processing webhook data. See the Webhooks Guide for implementation examples in Node.js and Python.

Example Webhook Payload

{
  "payload": {
    "contact": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "abc123-def456-ghi789",
      "jobId": "job-uuid-here",
      "clientId": "client-uuid-here",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phones": [
        {
          "number": "+15551234567",
          "status": "p1 - ivr",
          "type": "hq",
          "country": "US",
          "region": "US",
          "position": 1,
          "ivrPath": "#4021"
        },
        {
          "number": "+15559876543",
          "status": "p2",
          "type": "mobile",
          "country": "US",
          "region": "US",
          "position": 2,
          "ivrPath": null
        },
        {
          "number": "+15552223333",
          "status": "p3",
          "type": "TitanX Enriched Phone 1",
          "country": "US",
          "region": "US",
          "position": 3,
          "ivrPath": null
        }
      ],
      "bestPhone": {
        "number": "+15551234567",
        "status": "p1 - ivr",
        "ivrPath": "#4021"
      },
      "title": "VP of Sales",
      "companyAccount": "Acme Corp",
      "website": "https://acme.com",
      "linkedInUrl": "https://linkedin.com/in/johndoe",
      "companyLinkedInUrl": "https://linkedin.com/company/acme",
      "city": "San Francisco",
      "stateProvince": "CA",
      "country": "USA",
      "companyCity": "San Francisco",
      "companyState": "CA",
      "companyCountry": "USA",
      "numberOfEmployees": "501-1000",
      "annualRevenue": "$50M-$100M",
      "industry": "Technology",
      "leadStatus": "P1",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:35:00Z"
    },
    "job": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "scoring"
    }
  },
  "eventType": "job.contact.scored",
  "timestamp": 1705318200000,
  "apiVersion": "v2",
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

The flat phone/phone2–phone5 fields (and their Status/Type/Country/Region variants) are still present in the payload for backward compatibility but are deprecated. New integrations should read phone data from the phones[] array, which is canonical and also surfaces enrichment phones beyond the five-number cap.

OpenAPI Definition

The complete OpenAPI 3.1 specification for this webhook callback is available in the openapi.json file under the webhooks section:

webhooks:
  job.contact.scored:
    post:
      summary: job.contact.scored webhook callback
      # Full specification in openapi.json

The webhook payload uses the same Contact schema as other API endpoints. This ensures consistency across the API and means any updates to the Contact schema automatically apply to webhook payloads.

Overview

Contact Data

Job Management

Account

Webhook Management

Webhook Callbacks

Overview

Webhook Specification

POST job.contact.scored

Headers

Request Body

Expected Response

Retry Policy

Security Requirements

Signature Verification

Example Webhook Payload

OpenAPI Definition

​Overview

​Webhook Specification

​POST job.contact.scored

​Headers

​Request Body

​Expected Response

​Retry Policy

​Security Requirements

​Signature Verification

​Example Webhook Payload

​OpenAPI Definition

Overview

Webhook Specification

POST job.contact.scored

Headers

Request Body

Expected Response

Retry Policy

Security Requirements

Signature Verification

Example Webhook Payload

OpenAPI Definition