Skip to main content
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.

​
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'];
  const webhookKey = req.headers['x-webhook-key'];
  // If you have a webhook key configured, verify it matches your stored key; reject with 401 if not
  if (process.env.WEBHOOK_KEY && webhookKey !== process.env.WEBHOOK_KEY) {
    return res.status(401).json({ error: 'Invalid webhook key' });
  }

  // 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 events for resume processing, job changes, and candidate actions. Each request uses a common payload structure and headers. For a full reference of every event type, payload shape, and field descriptions, see Webhook event types.

​
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 X-Webhook-Key header: When you have generated a webhook key in the dashboard (Account Settings > Developers > API Key Management, under Webhook Configuration), TapTalent sends it in this header. Verify that it matches the key you stored when you generated or refreshed it. If you have a key configured and the header does not match, reject the request. The key is shown only once when you create or refresh it; store it securely.
Webhook signature verification may be added in a future release in addition to the key. This section will be updated with any new verification details.

​
Best Practices

  • Use HTTPS: Always use HTTPS for webhook endpoints
  • Verify X-Webhook-Key: If you have a webhook key configured, validate that the X-Webhook-Key header equals your stored key before processing the payload. Reject requests that do not match (e.g. 401 Unauthorized).
  • 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

​
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