WebHooks

Introduction

External applications can be notified of iCoStaffTime events using WebHooks.

The destination URL for these notifications is configured when a external application is registered with iCoStaffTime.

The events that an external application can be notified of changes to:

  • Leave Allowances (manual adjustments)
  • Shifts
  • Expenses
  • Leave Requests
  • Overtime Requests
  • Timecard

Content

The body of the WebHook POST is JSON encoded and will contain data which was correct at the time the WebHook was initially invoked.

Retries

Should a WebHook fail because the destination web server is unavailable or the response status code was not successful then it will be retried periodically up to 1 hour after the initial attempt.

Note that it is therefore possible, in the event of the destination web server being temporarily unavailable, that the updates successfully received may be out of order.

Authentication

The content will be signed using the WebHook’s configured Secret Token so you can be sure that the content originated from iCoStaffTime. This signature takes the form of the additional HTTP header “X-ICOSTAFFTIME-SIGNATURE-HMAC-SHA256” whose value is the HMAC_SHA256 of the Secret Token and the HTTP body.

An example HTTP header might look like:

X-ICOSTAFFTIME-SIGNATURE-HMAC-SHA256: b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad

Message field types

id, organisation_id, resource_id, approved_by, created_by, updated_by, declined_by
All ids are strings with max length 36 and are typically UUIDs (automated actions are attributed to id automated_approval).
created_at, updated_at, approved_at, cancelled_at, declined_at
All times use RFC3339 and are always in UTC e.g. (2017-01-02T09:30:00Z).
shift.repeat.days
Repeat this shift every X days (7=weekly, 14=bi-weekly).
shift.repeat.weekdays
Days of week are integers with Sunday=0.
rules_failed.action
Action taken when a rule does not pass. Can be either approve | decline | manual.
timecard.instance_id
Composed by the appending the shift_id “#” and the shift instance offset (e.g. 0=first instance, 1=second instance).

Example messages

Allowance

{
  "allowance": {
    "start_at": "2016-01-01T00:00:00Z",
    "end_at": "2017-01-01T00:00:00Z",
    "id": "a9a89131-35db-4ec3-9d33-34efb56eb8f6",
    "organisation_id": "3b95e29e-563f-4148-a166-79e23372cb02",
    "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
    "type_id": "holiday_paid",
    "duration_ns": 756000000000000,
    "created_at": "2016-10-13T07:12:00Z",
    "created_by": "e3525875-20d1-4272-ae28-4846048da4e1",
    "updated_at": "2016-10-13T07:12:00Z",
    "updated_by": "e3525875-20d1-4272-ae28-4846048da4e1"
  }
}

Shift

{
  "shift": {
    "start_at": "2016-10-13T14:00:00Z",
    "end_at": "2016-10-13T18:30:00Z",
    "id": "dbede686-5782-47d3-a30c-963ae0f96505",
    "organisation_id": "3b95e29e-563f-4148-a166-79e23372cb02",
    "title": "Waiter",
    "description": "A sample description which can contain links \u003ca href=\"https://www.icostafftime.com/\"\u003eiCoStaffTime\u003c/a\u003e.",
    "tags": [
      "ExampleJobTag"
    ],
    "repeat": {
      "start_at": "2016-10-13T14:00:00Z",
      "end_at": "2017-10-13T18:30:00Z",
      "days": 7,
      "weekdays": [
        1,
        2,
        3,
        4,
        5
      ],
      "cancelled": [
        {
          "start_at": "2016-11-13T14:00:00Z",
          "end_at": "2016-12-13T14:00:00Z",
          "cancelled_at": "2016-10-10T12:21:02Z"
        }
      ]
    },
    "inked_at": "2016-10-10T12:14:02Z",
    "cancelled_at": null,
    "created_at": "2016-10-10T12:11:02Z",
    "created_by": "e3525875-20d1-4272-ae28-4846048da4e1",
    "updated_at": "2016-10-10T12:21:02Z",
    "constraint": {
      "accepted_min": 1,
      "accepted_max": 1,
      "replied_min": 1
    },
    "subjects": [
      {
        "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
        "accepted_at": "2016-10-11T03:10:30Z",
        "declined_at": null,
        "expires_at": "2017-01-01T00:00:00Z",
        "cancelled_from": null,
        "cancelled_at": null,
        "updated_at": "2016-10-11T03:10:30Z"
      }
    ]
  }
}

Expense

{
  "expense": {
    "id": "36213817-2dfd-4b4a-9df6-a21c8ba6c875",
    "organisation_id": "3b95e29e-563f-4148-a166-79e23372cb02",
    "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
    "shift_id": "dbede686-5782-47d3-a30c-963ae0f96505",
    "instance_id": "dbede686-5782-47d3-a30c-963ae0f96505#0",
    "timestamp": "2016-10-13T07:12:00Z",
    "type_id": "travel:parking",
    "amount": {
      "unit": "GBP",
      "amount": 1.8,
      "label": "£ 1.80"
    },
    "description": "Parking charge",
    "receipt_id": "30ef2165-accd-4593-9f3e-c7a8f04fb02d",
    "created_at": "2016-10-13T07:12:00Z",
    "approved_at": "2016-10-13T10:55:00Z",
    "approved_by": "e3525875-20d1-4272-ae28-4846048da4e1",
    "declined_at": null,
    "declined_by": null,
    "cancelled_at": null,
    "updated_at": "2016-10-13T10:55:00Z"
  }
}

Leave

{
  "leave": {
    "start_at": "2016-01-08T09:00:00Z",
    "end_at": "2016-01-10T18:00:00Z",
    "id": "c6f0d28a-7125-44a4-8b40-6349d68aff91",
    "organisation_id": "3b95e29e-563f-4148-a166-79e23372cb02",
    "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
    "type_id": "holiday_paid",
    "description": "Family trip",
    "rules_failed": [
      {
        "description": "A generated description generated when checking for auto approval when initially submitted",
        "error": "Name of rule as configured by organisation",
        "priority": 0,
        "action": "manual"
      }
    ],
    "created_at": "2016-10-13T07:12:00Z",
    "approved_at": "2016-10-13T10:55:00Z",
    "approved_by": "e3525875-20d1-4272-ae28-4846048da4e1",
    "declined_at": null,
    "declined_by": null,
    "cancelled_at": null,
    "updated_at": "2016-10-13T10:55:00Z"
  }
}

Overtime

{
  "overtime": {
    "start_at": "2016-09-10T17:00:00Z",
    "end_at": "2016-09-10T19:30:00Z",
    "id": "b955f374-167e-4a55-afc3-882fac9c6349",
    "organisation_id": "3b95e29e-563f-4148-a166-79e23372cb02",
    "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
    "description": "Cover Jack",
    "rules_failed": [
      {
        "description": "A generated description generated when checking for auto approval when initially submitted",
        "error": "Name of rule as configured by organisation",
        "action": "manual"
      }
    ],
    "created_at": "2016-10-13T07:12:00Z",
    "approved_at": "2016-10-13T10:55:00Z",
    "approved_by": "e3525875-20d1-4272-ae28-4846048da4e1",
    "declined_at": null,
    "declined_by": null,
    "cancelled_at": null,
    "updated_at": "2016-10-13T10:55:00Z"
  }
}

Timecard

{
  "timecard": {
    "id": "3ca90b9d-67f1-4a2a-8254-f85a4fdd7a9c",
    "organisation_id": "3b95e29e-563f-4148-a166-79e23372cb02",
    "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
    "shift_id": "dbede686-5782-47d3-a30c-963ae0f96505",
    "instance_id": "dbede686-5782-47d3-a30c-963ae0f96505#0",
    "created_at": "2016-09-16T11:31:23Z",
    "approved_at": "2016-10-13T10:55:00Z",
    "approved_by": "e3525875-20d1-4272-ae28-4846048da4e1",
    "approval_id": null,
    "approval_at": null,
    "approval_by": null,
    "declined_at": null,
    "declined_by": null,
    "updated_at": "2016-10-13T10:55:00Z",
    "punches": [
      {
        "id": "26a36949-5965-4b91-8720-d00bcf300ac0",
        "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
        "timecard_id": "3ca90b9d-67f1-4a2a-8254-f85a4fdd7a9c",
        "in": true,
        "timestamp": "2016-09-16T11:31:23Z",
        "offline": false,
        "latitude": 0.00102,
        "longitude": 0.00132,
        "created_at": "2016-09-16T11:31:27Z",
        "created_by": "2794e543-5608-42e9-95b1-677df96071b7"
      },
      {
        "id": "6950cd69-9f3a-4b82-8fe4-76fa0b5c19a1",
        "resource_id": "2794e543-5608-42e9-95b1-677df96071b7",
        "timecard_id": "3ca90b9d-67f1-4a2a-8254-f85a4fdd7a9c",
        "in": false,
        "timestamp": "2016-09-16T16:32:10Z",
        "offline": false,
        "latitude": 0.00122,
        "longitude": 0.00135,
        "created_at": "2016-09-16T16:32:27Z",
        "created_by": "2794e543-5608-42e9-95b1-677df96071b7"
      }
    ]
  }
}