Setting up webhook via API

Manage webhooks programmatically using the Webhook API.

Available Endpoints

Method	Endpoint	Description
POST	/settings/v1/webhooks	Create a webhook
GET	/settings/v1/webhooks	List all webhooks
GET	/settings/v1/webhooks/{webhookId}	Get a specific webhook
PUT	/settings/v1/webhooks/{webhookId}	Update a webhook
DELETE	/settings/v1/webhooks/{webhookId}	Delete a webhook

Authentication

API Key (X-API-KEY header), or
OAuth 2.0

Scope	Operations
`settings.read`	List and get webhooks
`settings.write`	Create and update webhooks
`settings.delete`	Delete webhooks

The account must include Webhooks, and the caller needs access to Settings.

Create Webhook

Request Body

Field	Type	Required	Description
name	string	Yes	Descriptive name for the webhook
url	string	Yes	HTTPS endpoint URL
featureType	string	Yes	`users`, `forms`, `time_activity`, `shift_scheduler`, `tasks`, or `chat`
entityId	string	No	Preferred scope ID. For Time Activity, use the Time Clock ID as a string, for example `"67"`. Omit it for a broadcast subscription
objectId	integer	No	Deprecated. Legacy numeric scope ID. Use `entityId`
eventTypes	array	Yes	At least one event type to subscribe to
webhookVersion	integer	No	Payload schema version. Defaults to `1`
isDisabled	boolean	No	Set to `true` to create the webhook disabled. Defaults to `false`
secretKey	string	No	Shared value sent unchanged in the `x-webhook-secret` request header. This is not an HMAC signature

Example: Create Users Webhook

curl --request POST \
  --url https://api.connecteam.com/settings/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "name": "User Sync Webhook",
    "url": "https://your-endpoint.com/webhooks/users",
    "featureType": "users",
    "eventTypes": ["user_created", "user_updated", "user_deleted"]
  }'

Example: Create Time Activity Webhook

curl --request POST \
  --url https://api.connecteam.com/settings/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "name": "Time Clock Events",
    "url": "https://your-endpoint.com/webhooks/timeclock",
    "featureType": "time_activity",
    "entityId": "12345678",
    "eventTypes": ["clock_in", "clock_out", "admin_add", "admin_edit", "user_add_request", "admin_day_locked", "user_timesheet_approved"]
  }'

Update Webhook

Update any field of an existing webhook. Only include fields you want to change.

curl --request PUT \
  --url https://api.connecteam.com/settings/v1/webhooks/493 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "url": "https://new-endpoint.com/webhooks",
    "isDisabled": true
  }'

Example: Add Time Activity events to an existing webhook

GET the webhook first, then PUT the previous eventTypes plus the new names. Events you omit are no longer delivered.

curl --request PUT \
  --url https://api.connecteam.com/settings/v1/webhooks/493 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "eventTypes": [
      "clock_in",
      "clock_out",
      "admin_add",
      "user_add_request",
      "user_edit_request",
      "user_delete_request",
      "admin_declined_add_request",
      "admin_declined_edit_request",
      "admin_declined_delete_request",
      "admin_day_locked",
      "admin_day_unlocked",
      "user_timesheet_submitted",
      "user_timesheet_unsubmitted",
      "user_timesheet_approved",
      "user_timesheet_reopened"
    ]
  }'

Get Webhook

Response

{
  "requestId": "42q3457b-z12c-1136-aeve-e0d433524457",
  "id": 493,
  "name": "Test users webhook",
  "userId": 9170357,
  "timeCreated": 1734074315,
  "url": "https://webhook.site/test",
  "isDisabled": false,
  "featureType": "users",
  "entityId": null,
  "objectId": null,
  "retryLimit": 3,
  "webhookVersion": 1,
  "eventTypes": [
    "user_created",
    "user_updated",
    "user_deleted"
  ]
}

Response Fields

Field	Type	Description
id	integer	Unique webhook identifier
name	string	Webhook name
userId	integer	ID of user who created the webhook
timeCreated	integer	Unix timestamp of creation
url	string	Webhook endpoint URL
isDisabled	boolean	Whether webhook is disabled
featureType	string	Feature type
entityId	string	Preferred scope ID. `null` for a broadcast subscription
objectId	integer	Deprecated legacy numeric scope ID
retryLimit	integer	Maximum retry count. The default is `3` after the initial attempt
webhookVersion	integer	Payload schema version
eventTypes	array	Subscribed event types

Scope and delivery security

For a webhook scoped to one Time Clock, set entityId to that Time Clock ID as a string. Omit both entityId and the deprecated objectId to receive matching events from all supported entities in the company.

When secretKey is set, Connecteam sends that exact value in the x-webhook-secret header. It does not sign or hash the request body. Compare the received header to your stored secret with a constant-time comparison.

import { timingSafeEqual } from 'node:crypto';

function hasValidWebhookSecret(request) {
  const received = Buffer.from(request.headers['x-webhook-secret'] || '');
  const expected = Buffer.from(process.env.CONNECTEAM_WEBHOOK_SECRET);
  return received.length === expected.length && timingSafeEqual(received, expected);
}

📝
Receiver checklist

Return any 2xx response within 10 seconds, then process the event asynchronously.

Retries resend the same JSON and may arrive without a fixed delay.

404 is treated as permanent and is not retried. Other failures may be retried up to 3 times.

requestId is a correlation ID, not a globally unique event ID. Different events caused by one action can share it.

For idempotency, combine requestId with eventType and the affected entity or date range.

Event Types by Feature

users

Event	Description
user_created	New user added
user_updated	User profile modified
user_deleted	User permanently deleted
user_archived	User archived
user_restored	User unarchived
user_promoted	User promoted to admin
user_demoted	Admin demoted to user

forms

Event	Description
form_submission	New form submitted
form_submission_edited	Submission edited by user
manager_field_updated	Manager fields updated

time_activity

Event	Description
clock_in	User clocked in
clock_out	User clocked out
auto_clock_out	Automatic clock out
admin_add	Admin added time entry
admin_edit	Admin edited time entry
admin_delete	Admin deleted time entry
admin_approved_add_request	Admin approved add request
admin_approved_edit_request	Admin approved edit request
admin_approved_delete_request	Admin approved delete request
admin_declined_request	Generic decline (kept for existing subscriptions). Prefer the three specific decline events below
auto_approved_add_request	Auto-approved add request
auto_approved_edit_request	Auto-approved edit request
auto_approved_delete_request	Auto-approved delete request
admin_approved_clock_out_outside_geo_fence_request	Admin approved geo-fence override
auto_approved_clock_out_outside_geo_fence_request	Auto-approved geo-fence override
admin_approved_clock_out_without_nfc_request	Admin approved NFC override
auto_approved_clock_out_without_nfc_request	Auto-approved NFC override
user_add_request	User submitted an add request (pending)
user_edit_request	User submitted an edit request (pending)
user_delete_request	User submitted a delete request (pending)
admin_declined_add_request	Admin declined a user add request
admin_declined_edit_request	Admin declined a user edit request
admin_declined_delete_request	Admin declined a user delete request
admin_day_locked	Admin locked a day or period for a user
admin_day_unlocked	Admin unlocked a day or period for a user
user_timesheet_submitted	User submitted a timesheet for approval
user_timesheet_unsubmitted	User withdrew a submitted timesheet
user_timesheet_approved	Admin approved a user's timesheet
user_timesheet_reopened	Admin reopened a user's timesheet

See the Time activity webhook guide for payload examples, including request lifecycle and timesheet period events.

shift_scheduler

Event	Description
shift_created	New shift created
shift_updated	Shift modified
shift_deleted	Shift deleted
availability_status_created	Availability added
availability_status_deleted	Availability removed

tasks

Event	Description
task_published	Task published
task_completed	Task marked complete

chat

📘
See also
See the Chat webhook guide for payloads and examples.

Event	Description
message_created	New message posted
message_updated	Message content edited
message_deleted	Message deleted
conversation_created	Conversation created
conversation_updated	Conversation edited, locked/unlocked, or renamed
conversation_deleted	Conversation deleted

API Reference

Available Endpoints

Authentication

Create Webhook

Request Body

Example: Create Users Webhook

Example: Create Time Activity Webhook

Update Webhook

Example: Add Time Activity events to an existing webhook

Get Webhook

Response

Response Fields

Scope and delivery security

Receiver checklist

Event Types by Feature

users

forms

time_activity

shift_scheduler

tasks

chat

See also

What’s Next