Skip to main content

​
Webhooks

Webhooks allow you to receive real-time notifications about events in the Taptalent platform. Instead of polling the API for updates, you can configure a webhook URL to automatically receive notifications when specific events occur.

​
What Are Webhooks

Webhooks are HTTP callbacks that send event data to your application when something happens in TapTalent. This enables real-time, event-driven integrations without the need to continuously poll the API.

​
When to Use Webhooks

  • High-volume integrations: Receive updates immediately without polling
  • Real-time synchronization: Keep your systems in sync with TapTalent
  • Event-driven workflows: Trigger actions in your system based on TapTalent events

​
Webhooks vs Polling

  • Webhooks: TapTalent sends data to your endpoint when events occur (recommended)
  • Polling: Your application periodically checks for updates (less efficient)

​
Webhook URL Configuration

Webhook URLs can only be configured through the TapTalent dashboard. This ensures proper authentication and access control. The webhook URL is configured at the company level and applies to all API key operations for that company.
Webhook URL configuration is not available via the Partner API. You must configure your webhook URL through the TapTalent dashboard interface.

​
Admin Restriction

Only users with the following roles can configure webhook URLs:
  • Company Admin
  • Admin
  • Super Admin

​
Webhook Setup Process

​
Step 1: Create a Webhook Endpoint

Create an HTTP endpoint in your application that can receive POST requests: 
app.post('/webhooks/taptalent', (req, res) => {
  // Verify webhook headers
  const eventType = req.headers['x-webhook-event'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  // Process the event
  const payload = req.body;
  
  // Respond quickly
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookEvent(eventType, payload).catch(error => {
    console.error('Webhook processing error:', error);
  });
});

​
Step 2: Configure Webhook URL

Webhook URLs must be configured through the TapTalent dashboard. Follow these steps:
  1. Log in to your Taptalent Dashboard
  2. Navigate to Account Settings > Developers > API Key Management
  3. Scroll to the Webhook Configuration section
  4. Enter your webhook URL (must be HTTPS)
  5. Click Save Webhook URL
Only administrators (Company Admin, Admin, or Super Admin) can configure webhook URLs. If you don’t have admin access, contact your administrator to set up the webhook URL.
The webhook URL is configured at the company level. Once set, it will be used for all webhook events related to your company’s API operations.

​
Step 3: Verify Your Endpoint

Ensure your webhook endpoint:
  • Is publicly accessible (not behind a firewall)
  • Uses HTTPS (required for security)
  • Responds quickly (within 5 seconds)
  • Returns a 2xx status code to acknowledge receipt

​
Webhook Events

TapTalent sends webhook events for various operations. All webhook payloads follow a consistent structure.

​
Webhook Payload Structure

{
  "event": "event.type.name",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "company-uuid",
  "data": {
    // Event-specific data
  }
}

​
Webhook Headers

All webhook requests include the following headers:
  • Content-Type: application/json
  • X-Webhook-Event: The event type (e.g., resume.bulk_upload_parse.started)
  • X-Webhook-Timestamp: ISO 8601 timestamp of when the event occurred

​
Supported Event Types

​
Resume Events

resume.bulk_upload_parse.started Triggered when a bulk resume upload batch starts processing. 
{
  "event": "resume.bulk_upload_parse.started",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "company-uuid",
  "data": {
    "batchId": "batch-uuid",
    "fileCount": 25
  }
}
resume.bulk_upload_parse.failed Triggered when a bulk resume upload batch fails. 
{
  "event": "resume.bulk_upload_parse.failed",
  "timestamp": "2024-01-20T14:45:00Z",
  "companyId": "company-uuid",
  "data": {
    "error": "Error message describing the failure"
  }
}
More event types will be added as new features are released. Check back for updates.

​
Security Considerations

​
HTTPS Required

Webhook endpoints must use HTTPS. TapTalent will not send webhooks to HTTP endpoints.

​
Webhook Verification

Currently, webhooks are identified by:
  • The X-Webhook-Event header containing the event type
  • The X-Webhook-Timestamp header with the event timestamp
  • The companyId in the payload matching your company
Webhook signature verification will be available in a future release. This section will be updated with verification details.

​
Best Practices

  • Use HTTPS: Always use HTTPS for webhook endpoints
  • Verify Company ID: Verify the companyId in the payload matches your company
  • Idempotency: Make your webhook handler idempotent to handle duplicate deliveries
  • Quick Response: Respond quickly (within 5 seconds) to avoid timeouts
  • Error Handling: Log errors and handle them gracefully
  • Rate Limiting: Implement rate limiting on your webhook endpoint

​
Retry Policy

TapTalent implements automatic retries for failed webhook deliveries:
  • Initial attempt: Immediate
  • Retry 1: After 200ms (exponential backoff)
  • Retry 2: After 400ms
  • Retry 3: After 800ms
After 3 failed retries, the webhook delivery is marked as failed. Failed webhooks are logged but not retried further.

​
Handling Retries

Your webhook endpoint should:
  • Return a 2xx status code to acknowledge successful receipt
  • Return a non-2xx status code if there’s an error (will trigger retry)
  • Be idempotent to handle duplicate deliveries from retries
  • Process webhooks asynchronously to respond quickly

​
Testing Webhooks

​
Webhook Receiver Endpoint

TapTalent provides a test webhook receiver endpoint for testing:

​
POST /v1/partner/webhook-receiver

This endpoint logs webhook payloads and can be used for testing webhook delivery. Example Request: 
curl -X POST "https://partner-api.taptalent.io/v1/partner/webhook-receiver" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event: resume.bulk_upload_parse.started" \
  -H "X-Webhook-Timestamp: 2024-01-20T14:45:00Z" \
  -d '{
    "event": "resume.bulk_upload_parse.started",
    "timestamp": "2024-01-20T14:45:00Z",
    "companyId": "company-uuid",
    "data": {
      "batchId": "batch-uuid",
      "fileCount": 25
    }
  }'
Example Response: 
{
  "received": true,
  "message": "Webhook received successfully",
  "payload": {
    "event": "resume.bulk_upload_parse.started",
    "timestamp": "2024-01-20T14:45:00Z",
    "companyId": "company-uuid",
    "data": {
      "batchId": "batch-uuid",
      "fileCount": 25
    }
  }
}

​
Company-Level Configuration

The webhook URL is configured at the company level and applies to all API key operations for that company. Only one webhook URL can be configured per company.

​
Troubleshooting

​
Webhook URL Not Saving

  • Verify you have administrator permissions
  • Check that the URL is valid and uses HTTPS
  • Ensure the URL is publicly accessible

​
Webhook Not Receiving Events

  • Verify your webhook URL is correctly configured
  • Check that your endpoint is publicly accessible
  • Ensure your endpoint responds with 2xx status codes
  • Check server logs for incoming requests
  • Verify HTTPS is properly configured

​
Webhook Delivery Failures

  • Check your endpoint logs for errors
  • Verify your endpoint responds within 5 seconds
  • Ensure your endpoint returns proper HTTP status codes
  • Check network connectivity and firewall rules

​
Next Steps