Setting Up Webhooks

Webhooks notify your application in real-time when events occur in Kula. Instead of polling the API, receive HTTP POST requests when candidates, applications, jobs, or offers change.

When to Use Webhooks

Use Case	Approach
Real-time updates	Webhooks
One-time data fetch	API call
Bulk data export	API with pagination
Event-driven workflows	Webhooks

Creating a Webhook via UI

The easiest way to create a webhook is through the Kula dashboard:

1. Log in to your Kula dashboard
2. Go to Settings → Webhooks
3. Click Create Webhook
4. Configure your webhook:
   • Webhook name — A descriptive name (e.g., "ATS Sync Production")
   • Description (optional) — Additional context about this webhook
   • Webhook URL — Your HTTPS endpoint that will receive events
   • Secret — Auto-generated, or provide your own for signature verification
   • Events to monitor — Select one or more events to subscribe to
5. Click Create to start receiving events

Use the auto-generated secret for signature verification. If you prefer your own secret, ensure it's a strong, randomly generated string. See Security & Authentication for verification details.

Creating a Webhook via API

For programmatic setup, use the Application API to create a webhook endpoint:

curl -X POST "https://api.kula.ai/v1/webhooks" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/kula",
    "events": ["application.created", "application.hired"]
  }'

Endpoint Requirements

Your webhook endpoint must:

• Accept HTTPS POST requests
• Respond with 2xx status within 10 seconds
• Handle duplicate deliveries (idempotent)

Managing Subscriptions

List Available Events

curl "https://api.kula.ai/v1/webhooks/events" \
  -H "Authorization: Bearer your_api_token_here"

Update Subscribed Events

curl -X PATCH "https://api.kula.ai/v1/webhooks/{id}" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["candidate.created", "candidate.updated"]
  }'

Endpoint Status

Status	Description
active	Receiving webhook deliveries
disabled	Not receiving webhooks

Endpoints are automatically disabled after 25 failures within 24 hours. Re-enable via:

curl -X POST "https://api.kula.ai/v1/webhooks/{id}/enable" \
  -H "Authorization: Bearer your_api_token_here"

Next Steps

• Event Payloads — Understand event data
• Security & Authentication — Verify webhook signatures