Guides

Scheduler webhook

Suggest Edits

Integrating with the scheduler webhooks enables real-time notifications about scheduling-related activities within the system. These events allow you to track and manage schedule changes, user availability updates, and related actions taken by users and admins.

🚧

Important to Know

This guide provides detailed information about scheduler-related webhook events. For the most up-to-date information and API references, visit the Connecteam Developer Documentation.

Events Overview

Below is a comprehensive list of events you can configure and expect to receive when using scheduler webhooks. These events help in monitoring various scheduling activities efficiently:

eventTypeDescription
availability_status_createdAn availability status for a user has been added.
availability_status_deletedAn availability status for a user has been removed.
shift_createdA new shift was created in the scheduler.
shift_updatedAn existing shift was updated in the scheduler.
shift_deletedA shift was deleted from the scheduler.

Additional Information Provided

Each event includes essential details to help you process and react to changes effectively. Below are the key components included in the webhook payloads:

  • eventType: Specifies the type of event that triggered the webhook (e.g., shift_created, availability_status_deleted).
  • requestId: Unique identifier of the webhook request for tracking purposes.
  • company: Identifier of the company associated with the event.
  • activityType: Type of activity associated with the event (e.g., shift, availability_status).
  • eventTimestamp: Unix timestamp indicating when the event occurred.
  • schedulerId: Identifier of the scheduler where the event was triggered.
  • data: Depending on the event type, this section contains further details, such as:
    • shifts (for shift_created and shift_updated): Array of shifts with fields similar to the Get Shifts response payload.
    • ids (for shift_deleted): Array of IDs of the deleted shifts.
    • availabilityStatuses (for availability_status_created and availability_status_deleted): Array of availability statuses, each including:
      • id: Unique identifier of the availability status.
      • type: Type of availability status (e.g., available, unavailable).
      • userId: ID of the user associated with the availability status.
      • start: Start time and timezone of the availability.
      • end: End time and timezone of the availability.
      • isAllDay: Indicates if the availability is for the entire day.
      • note: Notes or comments about the availability.
      • isAdminAction: Indicates whether the action was performed by an admin.

❗️

PAY ATTENTION

The payload contains an array of objects. For group shifts assigned to multiple users (e.g., 3 users), each user will trigger a separate shift creation event, therefore in the payload you can expect an array with 3 shift objects.

Please note that the parent group shift ID is not specified. Additionally, since our API does not support group shift creation or updates, it is not possible to edit or delete these shifts via the API.

Event Examples

Below are examples of JSON payloads for each type of event. These examples illustrate the structure and information included in the webhook payloads, enabling effective integration and processing.

Shift Created

{
  "eventType": "shift_created",
  "requestId": "b28d441c-e416-4c11-adb0-c8e0364ff29c",
  "company": "ihvttbbaqgxncryn",
  "activityType": "shift",
  "eventTimestamp": 1736760013,
  "schedulerId": 9454799,
  "data": {
    "shifts": [
      {
        "id": "6784dacb3c07733b0a849f49",
        "color": "",
        "assignedUserIds": [
          9170357
        ],
        "startTime": 1736924400,
        "endTime": 1736942400,
        "timezone": "Asia/Jerusalem",
        "isOpenShift": false,
        "title": "Morning",
        "jobId": "d4ad7232-576f-2ff6-c57d-8240f1089b00",
        "locationData": {
          "isReferencedToJob": true,
          "gps": {
            "address": "Times Square, Manhattan, NY, USA",
            "longitude": -73.9855426,
            "latitude": 40.7579747
          }
        },
        "isPublished": true,
        "isRequireAdminApproval": false,
        "updateTime": 1736760011,
        "creationTime": 1736760011,
        "notes": [],
        "statuses": [],
        "breaks": [],
        "shiftDetails": {
          "shiftLayers": []
        }
      }
    ]
  }
}

Shift Updated

{
  "eventType": "shift_updated",
  "requestId": "b28d441c-e416-4c11-adb0-c8e0364ff29c",
  "company": "ihvttbbaqgxncryn",
  "activityType": "shift",
  "eventTimestamp": 1736760013,
  "schedulerId": 9454799,
  "data": {
    "shifts": [
      {
        "id": "6784dacb3c07733b0a849f49",
        "color": "",
        "assignedUserIds": [
          9170357
        ],
        "startTime": 1736924400,
        "endTime": 1736942400,
        "timezone": "Asia/Jerusalem",
        "isOpenShift": false,
        "title": "Morning",
        "jobId": "d4ad7232-576f-2ff6-c57d-8240f1089b00",
        "locationData": {
          "isReferencedToJob": true,
          "gps": {
            "address": "Times Square, Manhattan, NY, USA",
            "longitude": -73.9855426,
            "latitude": 40.7579747
          }
        },
        "isPublished": true,
        "isRequireAdminApproval": false,
        "updateTime": 1736760011,
        "creationTime": 1736760011,
        "notes": [],
        "statuses": [],
        "breaks": [],
        "shiftDetails": {
          "shiftLayers": []
        }
      }
    ]
  }
}

Shift Deleted

{
  "eventType": "shift_deleted",
  "requestId": "5b496380-2053-414e-9a9e-983efefbb1b2",
  "company": "ihvttbbaqgxncryn",
  "activityType": "shift",
  "eventTimestamp": 1736760206,
  "schedulerId": 9454799,
  "data": {
    "ids": [
      "6784dacb3c07733b0a849f49"
    ]
  }
}

Availability Status Created

{
  "eventType": "availability_status_created",
  "requestId": "2907af4d-dae5-4778-b673-d2e437701b9c",
  "company": "ihvttbbaqgxncryn",
  "activityType": "shift_scheduler",
  "eventTimestamp": 1736760518,
  "schedulerId": 9454799,
  "availabilityStatuses": [
    {
      "id": "6784dcc39585f9dc60f7a6cb",
      "type": "unavailable",
      "userId": 9170357,
      "start": {
        "timestamp": 1736935200,
        "timezone": "Asia/Jerusalem"
      },
      "end": {
        "timestamp": 1736935200,
        "timezone": "Asia/Jerusalem"
      },
      "isAllDay": true,
      "note": ""
    }
  ],
  "isAdminAction": false
}

Availability Status Deleted

{
  "eventType": "availability_status_deleted",
  "requestId": "bc16a835-c3c6-4a94-83bb-694cf0c138b8",
  "company": "ihvttbbaqgxncryn",
  "activityType": "shift_scheduler",
  "eventTimestamp": 1736760523,
  "schedulerId": 9454799,
  "availabilityStatuses": [
    {
      "id": "6784dcc39585f9dc60f7a6cb",
      "type": "unavailable",
      "userId": 9170357,
      "start": {
        "timestamp": 1736935200,
        "timezone": "Asia/Jerusalem"
      },
      "end": {
        "timestamp": 1736935200,
        "timezone": "Asia/Jerusalem"
      },
      "isAllDay": true,
      "note": ""
    }
  ],
  "isAdminAction": false
}

Key Considerations

  • Testing: Before enabling webhooks in production, test the integration in a development environment to ensure correct processing of events.
  • Security: Validate incoming webhooks to ensure authenticity. Use webhook signatures for added security.
  • Event Handling: Implement retry logic in case of failures to process webhook events.
  • Payload Updates: Review the API documentation regularly for updates to payload structures and available events.

For further information, refer to the API Documentation or contact our support team.

Updated 9 days ago