Topics

Introduction

Teamtailor’s Company Webhooks allow you to receive real-time notifications when data changes in Teamtailor. This enables seamless integration with your existing systems without constantly polling the API.

Types of Webhook Systems in Teamtailor

Teamtailor offers two different webhook systems:

1. Company Webhooks - These are activated directly by companies in their Teamtailor settings. They allow companies to receive notifications about their own recruitment activities to any endpoint they configure.

2. Partner Webhook Setups - These are part of the partner integration system. When a client activates a partner integration that has a webhook setup, webhooks will be automatically activated for that company and sent to the endpoint configured in the partner’s webhook setup. These use a different authentication signature format and are enabled by Teamtailor for specific partner integrations.

This documentation focuses on Company Webhooks. For information about Partner Webhook Setups, please refer to the Partners documentation section.

Key Benefits

• Real-time updates: Get notified immediately when changes occur
• Flexible configuration: Subscribe only to the specific events you need
• Secured delivery: Verify webhook authenticity with signature validation
• Comprehensive payloads: Receive detailed information about changes

Use Cases

Company Webhooks are ideal for:

• Syncing candidate data with your CRM
• Updating your HRIS when job applications change status
• Triggering workflows when new jobs are created
• Building custom dashboards with real-time data

Setting Up Webhooks

Prerequisites

To use Company Webhooks, you need:

1. The Webhooks feature enabled for your company
2. Administrator permissions in Teamtailor
3. An endpoint that can receive webhook notifications (HTTPS required)

Configuration Steps

1. In Teamtailor dashboard, go to Settings > Integrations > Webhooks
2. Click Add webhook and provide:
   • Label: A descriptive name (e.g., “CRM Integration”)
   • Webhook URL: Your HTTPS endpoint
   • Events: Select the events you want to subscribe to
3. Save the automatically generated signature key for security verification
4. Test the connection to ensure your endpoint is receiving events

You can create multiple webhook subscriptions with different event filters to organize your integrations efficiently.

Event Types

Company Webhooks use a consistent naming pattern for events:

resource_name.action

Where: * resource_name is the object type (candidate, job, etc.) * action is what occurred (create, update, destroy)

Common Events

Candidate Events

• candidate.create - New candidate created
• candidate.update - Candidate information updated
• candidate.destroy - Candidate deleted

Job Events

• job.create - New job created
• job.update - Job information updated
• job.destroy - Job deleted

Job Application Events

• job_application.create - New application submitted
• job_application.update - Application updated (e.g., stage change)
• job_application.destroy - Application deleted

Webhook Payloads

When an event occurs, Teamtailor sends a JSON payload to your endpoint containing details about the event.

Payload Structure

{
  "payload": {
    "event_name": "job.update",
    "data": {
      "id": "2",
      "type": "jobs",
      "attributes": {
        "title": "IT Designer 1",
        "body": "<p>Job description...</p>",
        "company-name": "Teamtailor",
        "cover-letter-requirement": "cover_letter_optional",
        "created-at": "2023-02-08T10:10:13.611+01:00",
        "employment-level": "none",
        "employment-type": "none",
        "human-status": "archived",
        "internal": false,
        "remote-status": "none",
        "status": "archived",
        "tags": [],
        "updated-at": "2023-02-22T22:10:48.705+01:00"
      }
    }
  },
  "signature": "YzU1N2FhOTUwMjlkNTFiMGM5NjIxNTEyODc5NGY5ZjgxZWNkMmNkZTZhNmIxYmI2YmM3NmVmYmQ1ZGZiMDg0Zg=="
}

The standard payload structure includes:

1. payload: Object containing:
   • event_name: The type of event (e.g., “job.update”)
   • data: Resource data with:
     • id: Resource identifier
     • type: Resource type (e.g., “jobs”, “candidates”)
     • attributes: Resource-specific attributes
2. signature: Base64-encoded signature for verification

For destroy events, the data structure is simpler but follows the same overall structure.

Resource-Specific Attributes

Each resource type includes different attributes in the payload:

Candidate

• first_name, last_name, email, phone etc.
• tags, custom fields, status

Job

• title, body, status, company-name etc.
• employment details, dates, tags

Job Application

• candidate_id, job_id, stage etc.
• status, created_at, updated_at

Headers

Each webhook request includes these headers:

• TT-Signature: Signature for verifying webhook authenticity
• Authorization: Bearer token (for partner webhooks, if applicable)
• teamtailor-api-token: API token (if applicable)

Authentication & Security

Teamtailor uses multiple security measures to ensure webhook deliveries are secure and authentic.

Webhook Security

Each webhook request includes:

1. A TT-Signature header containing the signature
2. The same signature in the request body
3. Optional authorization headers for partner-specific webhooks

This allows you to verify that the webhook is legitimately from Teamtailor.

HTTPS Requirements

All webhook endpoints must use HTTPS to ensure data is encrypted in transit. Teamtailor will not send webhooks to non-HTTPS URLs.

Authentication Headers

Based on the implementation in tt-webhooks, the following headers may be present:

const headers = {
  "TT-Signature": signature,
};

if (providerKey) {
  headers.authorization = `Bearer ${providerKey}`;
}

if (apiKey) {
  headers["teamtailor-api-token"] = apiKey;
}

The standard header for signature verification is TT-Signature.

Retry Mechanism

If your endpoint is temporarily unavailable or returns a non-2xx status code, Teamtailor will retry the webhook delivery:

• First retry: Shortly after the initial attempt
• Subsequent retries: Using an exponential backoff strategy

After multiple failed attempts, if the webhook still fails to deliver, it will be logged as a failed delivery.

Webhook Signatures

To validate the authenticity of webhooks sent by Teamtailor, each request includes a TT-Signature header and a signature field in the payload. This allows you to verify the webhook came from Teamtailor.

Signature Format

The signature is a Base64-encoded hexadecimal string. In the example payload:

"signature": "YzU1N2FhOTUwMjlkNTFiMGM5NjIxNTEyODc5NGY5ZjgxZWNkMmNkZTZhNmIxYmI2YmM3NmVmYmQ1ZGZiMDg0Zg=="

Signature Verification

Based on the code in the tt-webhooks repository, the signature verification should follow this pattern:

const crypto = require('crypto');

// Get this from your webhook setup in Teamtailor
const SECRET_KEY = 'your_webhook_signature_key';

function verifyWebhookSignature(requestBody, signatureHeader) {
  const { payload } = requestBody;

  // Calculate expected signature
  // The exact calculation method may vary - check with Teamtailor for the exact formula
  const hmac = crypto.createHmac('sha256', SECRET_KEY)
    .update(payload.data.id.toString())
    .digest('hex');

  const expectedSignature = Buffer.from(hmac).toString('base64');

  // Compare signatures
  return signatureHeader === expectedSignature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['tt-signature'];

  if (!verifyWebhookSignature(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('Webhook processed');
});

Example Implementation (PHP)

<?php
// Get this from your webhook setup in Teamtailor
$secretKey = 'your_webhook_signature_key';

function verifySignature($requestBody, $signatureHeader, $secretKey) {
    $id = $requestBody['payload']['data']['id'];

    // Calculate the HMAC using SHA-256
    $hmac = hash_hmac('sha256', $id, $secretKey, true);

    // Convert to base64
    $expectedSignature = base64_encode(bin2hex($hmac));

    return hash_equals($signatureHeader, $expectedSignature);
}

// Webhook handler
$requestBody = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_TT_SIGNATURE'];

if (!verifySignature($requestBody, $signature, $secretKey)) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

// Process the webhook...
http_response_code(200);
echo 'Webhook processed';

Best Practices

Follow these best practices to ensure reliable and secure webhook integration with Teamtailor.

Implementation Recommendations

Webhook Processing

1. Verify signatures - Always verify the signature before processing webhooks
2. Process asynchronously - Handle webhooks asynchronously to respond quickly
3. Idempotency - Design your webhook handlers to be idempotent (can safely receive the same webhook multiple times)
4. Return quickly - Respond with a 200 status code as soon as possible, then process the webhook

Error Handling

1. Graceful failures - Handle errors gracefully and log issues for debugging
2. Webhook monitoring - Monitor webhook deliveries and failures
3. Handle retries - Be prepared for webhooks to be retried if your endpoint is temporarily unavailable

Performance Considerations

1. Selective subscriptions - Only subscribe to the events you need
2. Efficient processing - Process webhooks efficiently to avoid bottlenecks
3. Scalable infrastructure - Ensure your webhook endpoint can handle bursts of traffic

Security Guidelines

1. HTTPS only - Always use HTTPS for webhook endpoints
2. Signature verification - Always verify webhook signatures
3. Secrets management - Securely store your webhook signature key
4. Input validation - Validate webhook payloads before processing

Handling Duplicate Events

Webhooks might be delivered multiple times, especially during retries: - Use a unique identifier (like the event ID) to detect duplicates - Make your webhook processing idempotent

Partner Webhook Setups

Partner webhook setups are a specialized type of webhook system specifically designed for Teamtailor integration partners.

Key Differences from Company Webhooks

Partner webhook setups differ from company webhooks in several important ways:

1. Automatic Activation: When a client activates a partner integration that has a webhook setup, webhooks are automatically activated for that company without requiring additional configuration.

2. Partner-Managed Endpoints: The webhook endpoint is configured by the partner, not the client company.

3. Different Authentication: Partner webhooks use a different authorization header format and signature verification method.

4. Controlled Access: This feature is enabled by Teamtailor specifically for approved integration partners.

Authentication for Partner Webhooks

Partner webhook requests use a different authentication system than company webhooks:

Headers

• Authorization: Bearer token (JWT-encoded provider keys)
• Teamtailor-Signature: Format with timestamp (e.g., t=1539756759,v1=hmac,v0=hmac_fake)
• Teamtailor-Api-Token: API key when available
• Teamtailor-Host: Current TeamtailorStack host
• Content-Type: application/json

Company webhooks use a Base64-encoded HMAC SHA-256 signature calculated from the resource ID, while partner webhooks use a JWT-based authentication system with additional verification headers.

Setup Process

To set up partner webhook integrations:

1. Contact Teamtailor at integrations@teamtailor.com to request partner integration status
2. Teamtailor will enable the webhook setup feature for your partner account
3. Configure your endpoint to properly handle and authenticate the incoming webhooks