Guides

Overview

Webhooks deliver real-time notifications when events occur in Connecteam, eliminating the need for polling.

Available Webhooks

WebhookEventsDescription
Time Activityclock_in, clock_out, user_add_request, admin_day_locked, user_timesheet_approved, and moreTime clock punches, pending requests, day locks, and timesheet approval
Form Submissionform_submission, form_submission_edited, manager_field_updatedForm entries and updates
Usersuser_created, user_updated, user_deleted, user_archived, user_restored, user_promoted, user_demotedUser lifecycle events
Schedulershift_created, shift_updated, shift_deleted, availability_status_created, availability_status_deletedShift and availability changes
Taskstask_published, task_completedQuick task events
Chatmessage_created, message_updated, message_deleted, conversation_created, conversation_updated, conversation_deletedChat message and conversation events

Setup Methods

Via UI

  1. Go to Settings → API & Integrations
  2. Click Add webhook
  3. Configure:
    • Name: Descriptive name for your webhook
    • URL: Your HTTPS endpoint
    • Feature: Select the feature type
    • Object: Select the specific instance (e.g., which time clock)
    • Events: Choose which events to receive
  4. Click Create webhook
🚧

Important

Only account Owners can create webhooks. The endpoint URL must be HTTPS.

Via API

See Setting up webhook via API for programmatic webhook management.

Webhook Behavior

  • Retry logic: Failed deliveries are retried up to 3 times. There is no fixed delay, so a retry may arrive immediately. Any 2xx response succeeds; 404 is treated as permanent and is not retried; other failures may be retried.
  • Payload format: JSON. Shared envelope fields are requestId, company, eventType, eventTimestamp, and activityType. Some webhooks (Users, Tasks) nest details under data. Time Activity is flat — fields such as userId, timeClockId, and timeActivity sit at the root. See Time activity webhook.
  • Timeout: Return a 2xx response within 10 seconds. Queue longer processing after acknowledging the delivery.

Common Payload Structure

Most webhook payloads share these base fields. Time Activity does not wrap the event in data.

{
  "requestId": "unique-request-id",
  "company": "company_identifier",
  "eventType": "event_name",
  "eventTimestamp": 1736760013,
  "activityType": "feature_type"
}
FieldTypeDescription
requestIdstringCorrelation ID inherited from the originating action. Retries keep the same value, and different events from one action may share it
companystringCompany identifier
eventTypestringThe event that triggered this webhook
eventTimestampintegerUnix timestamp of the event
evnetTimestampintegerDeprecated misspelling. Still sent on older events (Users, and older Time Activity types). New Time Activity request, decline, and period events send eventTimestamp only
activityTypestringFeature type (for example User, Task, forms, shift, timesheet_period)
dataobject or arrayEvent-specific payload on Users, Forms, Tasks, and similar. Omitted on Time Activity

Receiving webhooks safely

  1. Validate x-webhook-secret when you configured a secretKey.
  2. Return any 2xx response within 10 seconds.
  3. Queue business processing after acknowledging the request.
  4. Expect retries to resend the same JSON.
  5. Do not deduplicate on requestId alone. Combine it with eventType and the affected entity (timeActivity.id, timeActivityId, or the user/date range).

API Reference

Updated 6 days ago

What’s Next

Did this page help you?