> ## Documentation Index
> Fetch the complete documentation index at: https://docs.titanx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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
```bash
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
```json
{
  "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.



## OpenAPI

````yaml /api-reference/openapi.json post /api/public/v2/webhooks
openapi: 3.1.0
info:
  version: 2.0.0
  title: TitanX API
  description: |-
    # TitanX API Documentation

    Welcome to the TitanX API!

    ## Base URL

    ```
    https://app.titanx.io/api/public/v2
    ```

    ## Authentication

    All endpoints require Bearer token authentication:

    ```http
    Authorization: Bearer YOUR_API_KEY
    ```

    ## Response Format

    All endpoints return responses in this consistent format:

    ```json
    {
      "data": { /* Your requested data */ },
      "credits": {
        "creditsCharged": 5,
        "creditsRemaining": 995,
        "costPerPhone": 0.05,
        "phoneCount": 100
      },
      "error": null
    }
    ```
servers:
  - url: https://app.titanx.io
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: v2
    description: ✅ Version 2 API (Current)
    externalDocs:
      description: V2 API Guide
      url: https://docs.titanx.io/api/v2
  - name: v2-contacts
    description: V2 Contact operations - scoring and enrichment with credit tracking
  - name: v2-jobs
    description: V2 Job operations - job management and contact retrieval
  - name: v2-account
    description: V2 Account operations - credits and billing information
  - name: v2-webhooks
    description: >-
      V2 Webhook operations - manage webhook subscriptions for real-time contact
      event notifications
paths:
  /api/public/v2/webhooks:
    post:
      tags:
        - v2
        - v2-webhooks
      summary: Create a new webhook subscription
      description: >-
        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

        ```bash

        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

        ```json

        {
          "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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: >-
            Webhook created successfully. The secret is only shown once - store
            it securely.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          description: Invalid request - validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateWebhookRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Name for the webhook (for your reference)
          example: Production Contact Webhook
        url:
          type: string
          format: uri
          description: HTTPS endpoint URL where webhook events will be sent (must be HTTPS)
          example: https://api.example.com/webhooks/titanx
        events:
          type: array
          items:
            type: string
            enum:
              - job.contact.scored
              - job.completed
          minItems: 1
          description: Array of event types to subscribe to
          example:
            - job.contact.scored
        status:
          type: string
          enum:
            - active
            - inactive
          default: active
          description: Initial status of the webhook
          example: active
      required:
        - name
        - url
        - events
    WebhookResponse:
      type: object
      properties:
        payload:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Unique webhook identifier
              example: 550e8400-e29b-41d4-a716-446655440000
            name:
              type: string
              description: Webhook name
              example: Production Contact Webhook
            url:
              type: string
              format: uri
              description: Webhook endpoint URL
              example: https://api.example.com/webhooks/titanx
            triggers:
              type: array
              items:
                type: string
                enum:
                  - job.contact.scored
                  - job.completed
              description: Event types this webhook is subscribed to
              example:
                - job.contact.scored
            status:
              type: string
              enum:
                - active
                - inactive
              description: Current webhook status
              example: active
            secret:
              type: string
              description: >-
                HMAC secret for signature verification (only shown once at
                creation)
              example: wh_sk_Xp2s9K4mN8vR1qW5tY7uI0oP3aS6dF9gH2jK4lZ8xC1vB5nM7
            createdAt:
              type: string
              format: date-time
              description: Webhook creation timestamp
              example: '2024-01-15T10:30:00Z'
            updatedAt:
              type: string
              format: date-time
              description: Last update timestamp
              example: '2024-01-15T10:30:00Z'
          required:
            - id
            - name
            - url
            - triggers
            - status
            - secret
            - createdAt
            - updatedAt
      required:
        - payload
    WebhookErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: 'Invalid webhook ID: must be a valid UUID'
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````