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

1. Create a webhook using this endpoint with your HTTPS URL
2. Store the secret returned in the response (shown only once)
3. Receive events at your endpoint when contacts are scored
4. Verify signatures using the secret and the X-TitanX-Signature header
5. 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:

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

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