Create a new webhook subscription

curl --request POST \
  --url https://app.titanx.io/api/public/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production Contact Webhook",
  "url": "https://api.example.com/webhooks/titanx",
  "events": [
    "job.contact.scored"
  ],
  "status": "active"
}
'

import requests

url = "https://app.titanx.io/api/public/v2/webhooks"

payload = {
    "name": "Production Contact Webhook",
    "url": "https://api.example.com/webhooks/titanx",
    "events": ["job.contact.scored"],
    "status": "active"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Production Contact Webhook',
    url: 'https://api.example.com/webhooks/titanx',
    events: ['job.contact.scored'],
    status: 'active'
  })
};

fetch('https://app.titanx.io/api/public/v2/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.titanx.io/api/public/v2/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production Contact Webhook',
    'url' => 'https://api.example.com/webhooks/titanx',
    'events' => [
        'job.contact.scored'
    ],
    'status' => 'active'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.titanx.io/api/public/v2/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"Production Contact Webhook\",\n  \"url\": \"https://api.example.com/webhooks/titanx\",\n  \"events\": [\n    \"job.contact.scored\"\n  ],\n  \"status\": \"active\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.titanx.io/api/public/v2/webhooks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Production Contact Webhook\",\n  \"url\": \"https://api.example.com/webhooks/titanx\",\n  \"events\": [\n    \"job.contact.scored\"\n  ],\n  \"status\": \"active\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.titanx.io/api/public/v2/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production Contact Webhook\",\n  \"url\": \"https://api.example.com/webhooks/titanx\",\n  \"events\": [\n    \"job.contact.scored\"\n  ],\n  \"status\": \"active\"\n}"

response = http.request(request)
puts response.read_body

{
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Contact Webhook",
    "url": "https://api.example.com/webhooks/titanx",
    "triggers": [
      "job.contact.scored"
    ],
    "status": "active",
    "secret": "wh_sk_Xp2s9K4mN8vR1qW5tY7uI0oP3aS6dF9gH2jK4lZ8xC1vB5nM7",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

{
  "error": "Invalid webhook ID: must be a valid UUID"
}

{
  "error": "Invalid webhook ID: must be a valid UUID"
}

Webhook Management

Create a new webhook subscription

Create a webhook subscription to receive real-time notifications when contact events occur.

Overview

Webhooks enable your application to receive real-time notifications when specific events happen in TitanX. Instead of polling for changes, webhooks push event data directly to your configured endpoint.

Important Security Note

The webhook secret is only returned once at creation time. Store it securely - you’ll need it to verify webhook signatures. If lost, you must delete and recreate the webhook.

Requirements

HTTPS Required: Your webhook URL must use HTTPS for security
Valid URL: Must be a publicly accessible endpoint
Authentication: Webhooks fire only for API-originated contact modifications by the authenticated user

Supported Events

Currently supported event types:

job.contact.scored - Fired when a contact completes scoring

How It Works

Create a webhook using this endpoint with your HTTPS URL
Store the secret returned in the response (shown only once)
Receive events at your endpoint when contacts are scored
Verify signatures using the secret and the X-TitanX-Signature header
Process the event data in your application

Example Webhook Creation

curl -X POST https://app.titanx.io/api/public/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/titanx",
    "eventTypes": ["job.contact.scored"]
  }'

Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://your-app.com/webhooks/titanx",
  "eventTypes": ["job.contact.scored"],
  "status": "active",
  "secret": "whsec_abc123def456...",  // Store this securely!
  "createdAt": "2024-01-15T10:30:00Z"
}

What Happens Next?

When a contact is scored via the API:

TitanX sends a POST request to your webhook URL
The request includes the event data and an HMAC signature
Your endpoint verifies the signature and processes the event
Your endpoint returns a 2xx status code to acknowledge receipt

For webhook payload structure and signature verification details, see the webhook callback documentation.

POST

api

public

webhooks

Create a new webhook subscription

curl --request POST \
  --url https://app.titanx.io/api/public/v2/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production Contact Webhook",
  "url": "https://api.example.com/webhooks/titanx",
  "events": [
    "job.contact.scored"
  ],
  "status": "active"
}
'

import requests

url = "https://app.titanx.io/api/public/v2/webhooks"

payload = {
    "name": "Production Contact Webhook",
    "url": "https://api.example.com/webhooks/titanx",
    "events": ["job.contact.scored"],
    "status": "active"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Production Contact Webhook',
    url: 'https://api.example.com/webhooks/titanx',
    events: ['job.contact.scored'],
    status: 'active'
  })
};

fetch('https://app.titanx.io/api/public/v2/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.titanx.io/api/public/v2/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production Contact Webhook',
    'url' => 'https://api.example.com/webhooks/titanx',
    'events' => [
        'job.contact.scored'
    ],
    'status' => 'active'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.titanx.io/api/public/v2/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"Production Contact Webhook\",\n  \"url\": \"https://api.example.com/webhooks/titanx\",\n  \"events\": [\n    \"job.contact.scored\"\n  ],\n  \"status\": \"active\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.titanx.io/api/public/v2/webhooks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Production Contact Webhook\",\n  \"url\": \"https://api.example.com/webhooks/titanx\",\n  \"events\": [\n    \"job.contact.scored\"\n  ],\n  \"status\": \"active\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.titanx.io/api/public/v2/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production Contact Webhook\",\n  \"url\": \"https://api.example.com/webhooks/titanx\",\n  \"events\": [\n    \"job.contact.scored\"\n  ],\n  \"status\": \"active\"\n}"

response = http.request(request)
puts response.read_body

{
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Contact Webhook",
    "url": "https://api.example.com/webhooks/titanx",
    "triggers": [
      "job.contact.scored"
    ],
    "status": "active",
    "secret": "wh_sk_Xp2s9K4mN8vR1qW5tY7uI0oP3aS6dF9gH2jK4lZ8xC1vB5nM7",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

{
  "error": "Invalid webhook ID: must be a valid UUID"
}

{
  "error": "Invalid webhook ID: must be a valid UUID"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name

string

required

Name for the webhook (for your reference)

Minimum string length: 1

Example:

"Production Contact Webhook"

url

string<uri>

required

HTTPS endpoint URL where webhook events will be sent (must be HTTPS)

Example:

"https://api.example.com/webhooks/titanx"

events

enum<string>[]

required

Array of event types to subscribe to

Minimum array length: 1

Available options:

job.contact.scored,

job.completed

Example:

["job.contact.scored"]

status

enum<string>

default:active

Initial status of the webhook

Available options:

active,

inactive

Example:

"active"

Response

Webhook created successfully. The secret is only shown once - store it securely.

payload

object

required

Show child attributes

Get account features

List all webhook subscriptions

⌘I

Overview

Contact Data

Job Management

Account

Webhook Management

Webhook Callbacks

Create a new webhook subscription

Overview

Important Security Note

Requirements

Supported Events

How It Works

Example Webhook Creation

Response Example

What Happens Next?

Authorizations

Body

Response