Webhook Callbacks

Overview

This documents the job.completed webhook callback that TitanX sends to your configured endpoint once an entire job has reached its terminal state. It is a job-level bookkeeping signal — it confirms a batch is done but carries no contact data. Each contact’s scored result was already delivered to you individually, in real time, via job.contact.scored as it was scored. A job is simply an organizational grouping of contacts; job.completed plays no role in data delivery.

Related Documentation:

Webhooks Guide - Implementation guide with code examples and event comparison
job.contact.scored callback - Per-contact webhook event
Webhook Management API - Endpoints to create and manage webhooks

When Does This Fire?

job.completed fires once per job when the job reaches a terminal state. This happens in one of two scenarios:

All contacts scored — every contact in the job has been fully processed and scored (jobStatus: "Finalized")
No contacts enriched — all contacts were rejected during enrichment, so the job is finalized as “Not Enriched” (jobStatus: "Not Enriched")

Timing depends on job size and current processing load.

job.contact.scored and job.completed are not alternatives. job.contact.scored is how you receive results — every contact fires its own event in real time as it is scored. job.completed delivers no contact data; use it for job-level bookkeeping, such as marking a batch complete in your UI once scoring is done.

POST job.completed

TitanX sends this POST request to your configured webhook URL when a job is fully finalized.

Headers

string

required

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

string

required

Always application/json

string

Example: TitanX-Webhooks/1.0

Request Body

object

required

Job summary data.

Show Payload Properties

string

required

Unique identifier of the finalized job (UUID).Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

enum

Type of the job. Use this to distinguish scoring vs. enrichment jobs and route the payload accordingly.Enum 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_rejectedExample: "scoring"

string

required

Human-readable name of the job as set at creation time.Example: "Q1 Outbound Campaign"

string

required

The job’s final status: "Finalized" when the job’s contacts were scored, or "Not Enriched" when every contact was rejected during enrichment.

string

required

ISO 8601 timestamp of when the job was finalized.Example: "2024-01-15T10:35:00Z"

string

required

Always "job.completed" for this callback.

number

required

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

string

required

API version. Currently "v2".

string

required

Unique identifier for this webhook delivery (UUID). Use this for idempotency.Example: "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"

Expected Response

Your endpoint should return a 2xx status code within 10 seconds.

Status Code	Behavior
`200-299`	Success — no retry
`400-499`	Client error — no retry (except 408, 429)
`408`, `429`	Will retry
`500-599`	Server error — will retry with exponential backoff

Example Payload

{
  "payload": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "jobType": "scoring",
    "jobName": "Q1 Outbound Campaign",
    "jobStatus": "Finalized",
    "modifiedAt": "2024-01-15T10:35:00Z"
  },
  "eventType": "job.completed",
  "timestamp": 1705318200000,
  "apiVersion": "v2",
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

Handling the Event

app.post('/webhooks/titanx', (req, res) => {
  // 1. Verify signature (always do this first)
  if (!verifySignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { eventType, payload, id } = req.body;

  // 2. Acknowledge immediately
  res.status(200).json({ received: true });

  // 3. Process asynchronously
  if (eventType === 'job.completed') {
    const { jobId, jobName, jobStatus, modifiedAt } = payload;

    // Contacts already arrived individually via job.contact.scored.
    // Do job-level bookkeeping here (e.g. mark this batch complete in your UI).
    console.log(`Job "${jobName}" finished scoring at ${modifiedAt}`);
  }
});

job.completed contains no contact data — you already have every contact from the per-contact job.contact.scored events, and the job is just an organizational grouping. If you need to reconcile or backfill a missed delivery, you can optionally call GET /api/public/v2/jobs/{jobId}/contacts, but treat it as a fallback rather than the primary way to get results.

Security

All webhook requests include X-TitanX-Signature. See Verifying Webhook Signatures for implementation examples in Node.js and Python.

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.completed:
    post:
      summary: job.completed webhook callback
      # Full specification in openapi.json

The webhook payload uses the JobCompletedWebhookEventPayload schema defined in the OpenAPI spec. This schema is generated directly from the application’s TypeScript types to ensure the documentation always matches the actual implementation.

Overview

Contact Data

Job Management

Account

Webhook Management

Webhook Callbacks

Overview

When Does This Fire?

POST job.completed

Headers

Request Body

Expected Response

Example Payload

Handling the Event

Security

OpenAPI Definition

​Overview

​When Does This Fire?

​POST job.completed

​Headers

​Request Body

​Expected Response

​Example Payload

​Handling the Event

​Security

​OpenAPI Definition

Overview

When Does This Fire?

POST job.completed

Headers

Request Body

Expected Response

Example Payload

Handling the Event

Security

OpenAPI Definition