Webhooks API

Webhooks allow you to receive real-time notifications when events occur in your TalentScreen account. Use them to trigger automated workflows in your systems.

Create Webhook

{
  "url": "https://api.yourcompany.com/webhooks/talentscreen",
  "events": ["exam.completed", "candidate.invited", "result.available"],
  "description": "Production webhook for ATS integration"
}

Available Events

Webhook Payload

All webhook events include a standard payload structure with event type, timestamp, and event-specific data.

{
  "id": "evt_bcd890",
  "event": "exam.completed",
  "timestamp": "2024-02-12T09:15:00Z",
  "data": {
    "result_id": "result_ghi789",
    "candidate_id": "cand_xyz789",
    "exam_id": "exam_abc123",
    "score": 87.5,
    "status": "passed",
    "completed_at": "2024-02-12T09:15:00Z"
  }
}

Verifying Webhooks

Each webhook request includes an X-TalentScreen-Signature header. Verify this signature to ensure the request came from TalentScreen.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

List Webhooks

Delete Webhook