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

X-TitanX-Signature

string

required

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

Content-Type

string

required

Always application/json

User-Agent

string

TitanX webhook user agentExample: TitanX-Webhooks/1.0

Request Body

payload

object

required

The complete scored Contact object with all available fields.

Show Contact Properties

string

Unique contact identifier (UUID)

userId

string

User ID who owns this contact (UUID)

jobId

string

Job ID this contact belongs to (UUID)

clientId

string

Client ID (UUID)

firstName

string

required

Contact’s first name

lastName

string

required

Contact’s last name

phone

string

required

Primary phone number

companyAccount

string

required

Company name

leadId

string

Lead identifier

fsTotalCalls

string

Total FullStory calls

string

Email address

title

string

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

phoneStatus

enum

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

phoneType

enum

Primary phone type. Possible values: mobile, direct, hq, other

phoneCountry

string

Primary phone country code (e.g., “US”)

phone2

string

Second phone number

phone2Status

enum

Second phone status (same values as phoneStatus)

phone2Type

enum

Second phone type (same values as phoneType)

phone2Country

string

Second phone country code

phone3

string

Third phone number

phone3Status

enum

Third phone status

phone3Type

enum

Third phone type

phone3Country

string

Third phone country code

phone4

string

Fourth phone number

phone4Status

enum

Fourth phone status

phone4Type

enum

Fourth phone type

phone4Country

string

Fourth phone country code

phone5

string

Fifth phone number

phone5Status

enum

Fifth phone status

phone5Type

enum

Fifth phone type

phone5Country

string

Fifth phone country code

phoneExt

string

Phone extension

linkedInUrl

string

Contact’s LinkedIn profile URL

street

string

Street address

city

string

City

stateProvince

string

State or province

zipPostalCode

string

ZIP or postal code

country

string

Country

timeZone

string

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

dept

string

Department (e.g., “Engineering”)

level

string

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

jobFunction

string

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

persona

string

Contact persona

website

string

Company website URL

companyLinkedInUrl

string

Company LinkedIn URL

companyAddress

string

Company street address

companyCity

string

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

companyState

string

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

companyZip

string

Company ZIP code

companyCountry

string

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

numberOfEmployees

string

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

annualRevenue

string

Revenue range (e.g., “

50M-

100M”)

industry

string

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

primarySubIndustry

string

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

sicCodes

string

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

naicsCodes

string

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

technologies

string

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

leadStatus

enum

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

campaignListName

string

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

recordOwner

string

Record owner (e.g., “[email protected]”)

contactCrmId

string

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

accountCrmId

string

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

databaseContactId

string

Database contact ID

databaseCompanyId

string

Database company ID

customerContactId

string

Customer contact identifier

enrichmentContactId

string

Enrichment contact ID

intent

string

Contact intent indicator (nullable)

unmappedFields

object

Additional unmapped fields as key-value pairs

createdAt

string

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

updatedAt

string

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

eventType

string

required

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

timestamp

number

required

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

apiVersion

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": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "phoneStatus": "p1",
    "phoneType": "mobile",
    "phone2": "+15559876543",
    "phone2Status": "p2",
    "phone2Type": "direct",
    "title": "VP of Sales",
    "companyAccount": "Acme Corp",
    "website": "https://acme.com",
    "city": "San Francisco",
    "stateProvince": "CA",
    "country": "USA",
    "companyCity": "San Francisco",
    "companyState": "CA",
    "companyCountry": "USA",
    "numberOfEmployees": "501-1000",
    "annualRevenue": "$50M-$100M",
    "industry": "Technology",
    "leadStatus": "P1"
  },
  "eventType": "job.contact.scored",
  "timestamp": 1705318200000,
  "apiVersion": "v2",
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

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

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