Use Webhooks to Integrate with a Payroll System

Applies to: Labor API

Learn how to subscribe to Labor API webhooks that send notifications about created, updated, and deleted labor shifts.

The Labor API supports the following webhook events:

A webhook is a subscription where you specify which events you want to be notified about. For information about using webhooks, see Square Webhooks. For a list of all webhook events supported by Square APIs, see Webhook Events Reference.

• Shift created - labor.shift.created
• Shift delete - labor.shift.deleted
• Shift updated - labor.shift.updated

The event notification body includes properties that identify the notification and a data object for the current state of the Shift that is changed.

Read the type property to identify the notification as a create, update, or delete notification. The merchant_id property identifies the merchant/employer of the worker associated with the shift.

The current state of the Shift is carried by the value of data.object.shift.

To access a Shift represented by a notification, your application requests TIMECARDS_READ permission when authenticating with the OAuth flow.

When a Shift is created (normally when an employee starts a shift), the webhook notification body includes a shift object representing the new shift.

If you use this event to synchronize an external payroll system with a Square Point of Sale time clock, use the value of data.object.shift.id to create a unique ID for the created shift in the payroll system.

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.created",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "shift",
    "id": "PY4YSMVKXFY9E",
    "object": {
      "shift": {
        "id": "PY4YSMVKXFY9E",
        "employee_id": "AnuhZhsN95oT8f-eCn9D",
        "team_member_id": "AnuhZhsN95oT8f-eCn9D",
        "location_id": "NAQ1FHV6ZJ8YV",
        "timezone": "Etc/UTC",
        "start_at": "2019-01-25T08:11:00Z",
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          },
          "job_id": "J8p7B7nyVA3QfMdnU1BkEfjP",
          "tip_eligible": true
        },
        "declared_cash_tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "status": "OPEN",
        "version": 1,
        "created_at": "2019-01-25T08:11:00Z",
        "updated_at": "2019-01-25T08:11:00Z"
      }
    }
  }
}

Shifts are created using a Square POS terminal or by calling CreateShift.

Call GetShift with data.object.shift.id to get the newest version of the Shift represented by the notification. The Shift returned by the GetShift call returns an equal or greater version value as the notification data.object.shift.version.

Shifts are updated when a break is started, a break is ended, or the shift ends. Other actions that trigger this event include updates to any read/write property.

If you use this event to synchronize an external payroll system with a Square Point of Sale time clock, use the value of data.object.shift.id to look up the shift in the payroll system.

The following example event body shows that a team member signed out for a break:

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.updated",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "shift",
    "id": "PY4YSMVKXFY9E",
    "object": {
      "shift": {
        "id": "PY4YSMVKXFY9E",
        "employee_id": "AnuhZhsN95oT8f-eCn9D",
        "team_member_id": "AnuhZhsN95oT8f-eCn9D",
        "location_id": "NAQ1FHV6ZJ8YV",
        "timezone": "Etc/UTC",
        "start_at": "2019-01-25T08:11:00Z",
        "end_at": "2019-01-25T18:11:00Z",
        "wage": {
          "title": "Barista",
          "hourly_rate": {
            "amount": 1100,
            "currency": "USD"
          },
          "job_id": "J8p7B7nyVA3QfMdnU1BkEfjP",
          "tip_eligible": true
        },
        "breaks": [
          {
            "id": "0EGK74E8BJF62",
            "start_at": "2019-01-25T11:11:00Z",
            "break_type_id": "REGS1EQR1TPZ5",
            "name": "Tea Break",
            "expected_duration": "PT5M",
            "is_paid": true
          }
        ],
        "declared_cash_tip_money": {
          "amount": 4830,
          "currency": "USD"
        },
        "status": "CLOSED",
        "version": 2,
        "created_at": "2019-01-25T08:11:00Z",
        "updated_at": "2019-01-25T18:09:37Z"
      }
    }
  }
}

Shifts are updated using a Square POS terminal or by calling UpdateShift.

Call GetShift with data.object.shift.id to get the newest version of the Shift represented by the notification. The Shift returned by the GetShift call returns an equal or greater version value as the notification data.object.shift.version.

When a Shift is deleted, the data object provides the id of the deleted shift. If you use this event to synchronize an external payroll system with a Square Point of Sale time clock, look up the ID of the deleted shift using the value of data.id.

{
  "merchant_id": "6SSW7HV8K2ST5",
  "type": "labor.shift.deleted",
  "event_id": "aeaaa5f6-c4fd-4e93-b688-71b50706266f",
  "created_at": "2019-10-29T17:26:16.808603647Z",
  "data": {
    "type": "labor",
    "id": "PY4YSMVKXFY9E",
    "deleted": true
  }
}

Shifts are deleted by calling DeleteShift.