Using Webhooks to notify other software

A webhook is an automatic message Cheqroom sends to another app the moment something happens in your workspace. Instead of another system repeatedly asking Cheqroom “anything new?”, Cheqroom pushes the update the instant an event occurs, such as an item being checked out, a reservation being made, or a work order being closed.

Webhooks let your other tools react in real time without anyone re-entering data. For example, you can:

Post a Slack or Teams message when a check-out goes overdue.
Update your ERP, CRM or ticketing system when an item’s location or status changes.
Start a custom workflow, such as a billing action in a finance tool when an item is checked in.
Keep an external reporting system in sync with Cheqroom.

To enable:

Click Settings in the bottom left corner of your screen
Click Integrations
Go to Webhooks
Click Configure

Setting up a webhook

Click New webhook
Give the webhook a name, pick the webhook Trigger and enter the URL
Click Add webhook

Each webhook listens to one topic. To be notified about several events, create one webhook per topic.

Webhooks are delivered as an HTTP POST with a JSON body (Content-Type: application/json). Your endpoint should respond within 30 seconds. If a webhook fails repeatedly, Cheqroom automatically disables it, so check the webhook's last status in your workspace if events stop arriving.

What webhooks are available?

Topics are named <object>.<action>. In webhook payloads, Check-outs appear as order, Users as contact, and Work Orders as ticket.

Items

Topic	Triggered when
`item.create`	An Item is created
`item.update`	A system field on an Item is updated
`item.delete`	An Item is deleted
`item.duplicate`	An Item is created by duplicating another Item
`item.setfield`	A custom field on an Item is updated
`item.clearfield`	A custom field on an Item is cleared
`item.setflag`	An Item flag is set
`item.clearflag`	An Item flag is cleared
`item.expire`	An Item is retired
`item.undoexpire`	An Item is unretired
`item.changelocation`	An Item's location is updated
`item.changeitemtype`	An Item's type is changed
`item.updatequantity`	The quantity of a bulk Item is changed
`item.addcomment`	A comment is added to an Item
`item.takecustody`	A contact takes custody of an Item
`item.transfercustody`	Item custody is transferred to another contact
`item.releasecustody`	A contact releases custody of an Item
`item.changegeo`	An Item's geo-location is updated
`item.updatecomment`	An Item comment is edited
`item.removecomment`	An Item comment is removed

Kits

Topic	Triggered when
`kit.addcomment`	A comment is added to a Kit
`kit.updatecomment`	A Kit comment is edited
`kit.removecomment`	A Kit comment is removed

Users (Contacts)

Topic	Triggered when
`contact.create`	A User or Contact is created
`contact.update`	A User or Contact is updated
`contact.delete`	A User or Contact is deleted
`contact.addcomment`	A comment is added to a User or Contact
`contact.block`	A User or Contact is blocked
`contact.undoblock`	A User or Contact is unblocked
`contact.setfield`	A custom field on a User or Contact is updated
`contact.clearfield`	A custom field on a User or Contact is cleared
`contact.updatecomment`	A User or Contact comment is edited
`contact.removecomment`	A User or Contact comment is removed
`contact.generatedocument`	A PDF is generated for a User or Contact

Reservations

Topic	Triggered when
`reservation.reserve`	A Reservation is made
`reservation.cancel`	A Reservation is cancelled
`reservation.close`	A Reservation is closed
`reservation.due`	A Reservation is due for pickup (see Due and overdue timing below)
`reservation.overdue`	A Reservation is overdue for pickup (see Due and overdue timing below)
`reservation.addcomment`	A comment is added to a Reservation
`reservation.generatedocument`	A Reservation PDF is generated
`reservation.undoreserve`	Making a Reservation is undone
`reservation.undoclose`	Closing a Reservation is undone
`reservation.setlabel`	A label is set on a Reservation
`reservation.clearlabel`	A label is cleared from a Reservation
`reservation.updatecomment`	A Reservation comment is edited

Check-outs (order)

Topic	Triggered when
`order.checkout`	A Check-out is checked out
`order.checkin`	A Check-out is checked in
`order.undocheckout`	A Check-out is undone
`order.extend`	A Check-out is extended
`order.due`	A Check-out is due (see Due and overdue timing below)
`order.overdue`	A Check-out is overdue (see Due and overdue timing below)
`order.addcomment`	A comment is added to a Check-out
`order.generatedocument`	A Check-out PDF is generated
`order.setlabel`	A label is set on a Check-out
`order.clearlabel`	A label is cleared from a Check-out
`order.updatecomment`	A Check-out comment is edited

Spotchecks

Topic	Triggered when
`spotcheck.close`	A Spotcheck is completed, with any outcome
`spotcheck.close_success`	A Spotcheck is completed without issues
`spotcheck.close_with_issues`	A Spotcheck is completed with issues, for example missing Items
`spotcheck.cancel`	A Spotcheck is cancelled
`spotcheck.undocancel`	Cancelling a Spotcheck is undone
`spotcheck.addcomment`	A comment is added to a Spotcheck
`spotcheck.updatecomment`	A Spotcheck comment is edited
`spotcheck.removecomment`	A Spotcheck comment is removed

Work Orders

Work Orders use the ticket prefix in webhook topics.

Topic	Triggered when
`ticket.create`	A Work Order is created
`ticket.update`	A Work Order is updated
`ticket.delete`	A Work Order is deleted
`ticket.duplicate`	A Work Order is duplicated
`ticket.open`	A Work Order is opened
`ticket.start`	A Work Order is started
`ticket.close`	A Work Order is closed
`ticket.cancel`	A Work Order is cancelled
`ticket.archive`	A Work Order is archived
`ticket.setassignee`	A Work Order's assignee is set
`ticket.setreporter`	A Work Order's reporter is set
`ticket.setfield`	A custom field on a Work Order is updated
`ticket.clearfield`	A custom field on a Work Order is cleared
`ticket.addcomment`	A comment is added to a Work Order
`ticket.generatedocument`	A Work Order PDF is generated
`ticket.undoopen`	Opening a Work Order is undone
`ticket.undostart`	Starting a Work Order is undone
`ticket.undoclose`	Closing a Work Order is undone
`ticket.undocancel`	Cancelling a Work Order is undone
`ticket.undoarchive`	Archiving a Work Order is undone
`ticket.setname`	A Work Order's name is set
`ticket.clearname`	A Work Order's name is cleared
`ticket.setdescription`	A Work Order's description is set
`ticket.cleardescription`	A Work Order's description is cleared
`ticket.setpriority`	A Work Order's priority is set
`ticket.clearpriority`	A Work Order's priority is cleared
`ticket.setdatefield`	A date field on a Work Order is set
`ticket.cleardatefield`	A date field on a Work Order is cleared
`ticket.changetickettype`	A Work Order's type is changed
`ticket.clearassignee`	A Work Order's assignee is cleared
`ticket.clearreporter`	A Work Order's reporter is cleared
`ticket.setlocation`	A Work Order's location is set
`ticket.clearlocation`	A Work Order's location is cleared
`ticket.setlabel`	A label is set on a Work Order
`ticket.clearlabel`	A label is cleared from a Work Order
`ticket.additems`	Items are added to a Work Order
`ticket.removeitems`	Items are removed from a Work Order
`ticket.addreservation`	A Reservation is linked to a Work Order
`ticket.removereservation`	A Reservation is unlinked from a Work Order
`ticket.addorder`	A Check-out is linked to a Work Order
`ticket.removeorder`	A Check-out is unlinked from a Work Order
`ticket.addticket`	A child Work Order is linked
`ticket.removeticket`	A child Work Order is unlinked
`ticket.updatecomment`	A Work Order comment is edited
`ticket.removecomment`	A Work Order comment is removed

Due and overdue timing

The order.due, order.overdue, reservation.due and reservation.overdue topics let you choose how many minutes before or after the due time the webhook fires:

Due topics fire the number of minutes you set before the due date and time.
Overdue topics fire the number of minutes you set after the due date and time.
A value of 0 fires exactly at the due date and time.

For example, to be notified one hour before a Check-out is due, use order.due with 60 minutes. Only open Check-outs and Reservations trigger these webhooks.

The older fixed-time topics (order.due_in_1_hour, order.due_in_1_day, order.overdue_1_hour, order.overdue_1_day and the matching reservation.* topics) still work for existing webhooks, but use .due and .overdue with a minutes value for new ones: 60 minutes replaces the 1-hour topics and 1440 minutes replaces the 1-day topics.

What's in the payload?

Every webhook POST wraps the affected object in the same envelope:

{   "data": { },   "time": 1234567890,   "id": "event-id",   "name": "your-webhook-name",   "topic": "order.checkout",   "kind": "order" }

Field	Description
`data`	The full object the event relates to (Item, Contact, Check-out, Reservation, Work Order and so on)
`time`	When the event was triggered, as a Unix timestamp
`id`	The event identifier
`name`	The name you gave the webhook
`topic`	The full topic, for example `order.checkout`
`kind`	The type of object: `item`, `kit`, `customer`, `order`, `reservation` or `ticket`

For .delete topics, data contains only the _id of the deleted record.

Signing webhooks

If you set a signing secret on a webhook, every POST for that webhook includes an X-CHEQROOM-Signature header. Its value is an HMAC SHA256 hex digest of the webhook payload, using the signing secret as the key.

Compute the signature of the payload in your code using the same shared secret and compare it to the header to verify that the webhook was triggered by Cheqroom.

Important

As of now, Cheqroom doesn't support incoming webhooks.