Setting Up Webhooks
Receive real-time notifications when events happen in TempClock by setting up webhook subscriptions.
Before You Start
Make sure you have everything you need to get up and running with webhooks.
Before you start
- A TempClock account with API access enabled (see API Setup Guide)
- An active API key with the webhooks:write scope
- An HTTPS endpoint on your server to receive webhook events
- Basic understanding of HTTP POST requests and JSON
Webhooks are ideal for CRM/ATS integrations (e.g. Salesforce, Bullhorn). Instead of polling the API for changes, your system gets notified instantly when clock-ins, worker updates, and shifts happen.
What Are Webhooks?
Understand how TempClock webhooks work before setting one up.
Webhooks are automatic HTTP POST requests that TempClock sends to your server whenever specific events occur. Think of them as real-time notifications:
Each webhook delivery includes the event type, a timestamp, and the relevant data, all signed with HMAC-SHA256 so you can verify authenticity.
TempClock supports these events: clock_in, clock_out, worker_created, worker_updated, shift_created, document_expired, and ping (for testing).
Step 1: Create a Webhook Subscription
Register your endpoint URL and choose which events to receive.
Send a POST request to the webhooks endpoint with your HTTPS URL and the events you want to subscribe to:
The response will include a signing secret. This is only shown once, so copy and store it securely:
Security: Store the signing secret in a secure location such as a password manager or environment variable. If you lose it, you will need to delete and re-create the subscription to get a new secret.
Step 2: Verify Webhook Signatures
Always validate that webhook deliveries genuinely came from TempClock.
Every webhook delivery includes an X-TempClock-Signature header. Compute the HMAC-SHA256 of the raw request body using your signing secret and compare it:
Always use constant-time comparison functions like hash_equals() in PHP or hmac.compare_digest() in Python to prevent timing attacks.
Step 3: Test Your Endpoint
Send a test ping to make sure everything is connected correctly.
Use the test action to send a ping event to your endpoint:
Your endpoint should receive a JSON payload like this:
If the test fails, check that your endpoint returns a 200 response code and that your URL is correct and accessible from the internet.
Step 4: Handle Incoming Events
Process webhook events in your application.
Each event has a different data payload. Here is what you can expect for the most common events:
entry_id, worker_id, worker_name, clock_in timestamp, location_id
entry_id, worker_id, worker_name, clock_in, clock_out, total_minutes, location_id
worker_id, worker_name, list of fields that changed
shift_id, worker_id, location_id, shift_date, start_time, end_time
Best practice: Return a 200 response immediately and process the event asynchronously (e.g. via a job queue). This prevents timeouts if your processing takes more than a few seconds.
Step 5: Monitor Deliveries
Track delivery status and check for failures.
Fetch a subscription by ID to see the last 10 delivery attempts:
The response includes a recent_deliveries array showing the event type, response code, attempt number, and timestamps for each delivery.
If you see consistent failures, check your endpoint's error logs and ensure it is returning a 2xx status code. Common issues include SSL certificate problems, firewall rules, and application errors.
Troubleshooting
Common issues and how to resolve them.
Verify your subscription is active, your URL is correct, and your server is accessible from the internet.
Make sure you are comparing against the raw request body (not parsed JSON) and using the correct signing secret.
Check that your API key has the webhooks:read and webhooks:write scopes.
Your endpoint must respond within 30 seconds. Process events asynchronously if your logic is complex.
Ready to try TempClock?
10-day free trial. All features included. No hidden fees, cancel anytime.