Incoming webhooks API reference
Incoming PACS webhooks let your access-control system tell UnSpot when employees enter or leave the office. UnSpot uses these events for automatic check-in of bookings and attendance analytics. Events are sent to a universal JSON endpoint that works with any PACS.
1. Create a subscription
Go to Manage → Integrations → Incoming webhooks, click “Create incoming webhook” (the window is titled “Add Incoming Subscription” — in this article “subscription” and “incoming webhook” mean the same thing) and choose JSON under “Data transfer method”. In the “Data Formatting Settings” block, specify which keys of your JSON hold the data — this is how UnSpot adapts to whatever your PACS sends. All four keys are required; when you create a subscription, the form fills in default values that you can change:
| Field in the window | What to enter | Default |
|---|---|---|
| Office | The key in which your PACS sends the access point — the turnstile or door the employee passed. UnSpot uses this value to determine the office of the visit (see “Office to access point mapping” below) | office |
| Location | The key holding a location name. The key has to be present in every event: an event without it is rejected | location |
| User | The key holding the employee identifier — email, pass number, full name or display name | email |
| Status | The key holding the direction: in_office — entry, out_office — exit | status |
The “Data Format Output” block of the window shows a sample JSON with your keys. “Add token” creates a secret token that has to be sent with every request in the Un-Token header. The token is shown only once — copy it before saving, it cannot be retrieved later. A subscription also works without a token.
After saving, the subscription appears in the list, and the “Your URL” column shows the address with the unique subscription token: your PACS POSTs events to it.
Subscriptions created before the Location field existed. If an older subscription has an empty Location field, the window will not save when you edit it — for example, to map access points — until the field is filled in. After that the location key has to be present in every event, so first make sure your PACS sends it, or enter a key that is always present in the events.
Office to access point mapping
At the bottom of the subscription window there is an “Office PACS access point mapping” block. UnSpot uses it to work out which office an employee entered. The block is optional: the subscription saves without it, but then no office is recorded for the events.
- Click “Add office” and under “Office” pick a space — an office or a space inside it, such as a floor. Disabled spaces are not listed.
- Under “Access points”, click “Add” and enter the value your PACS sends in the office key — for example, the name of a turnstile or door. The value is committed with Enter, by leaving the field or with the check mark.
- Repeat for the other access points of this office, and add a new row for another office. The “Delete” button removes a whole row.
Rules for access points:
- one office takes up to 100 access points — at the hundredth the “Add” button disappears; an access point name is up to 255 characters;
- leading and trailing spaces and letter case are ignored: access points are stored and shown in lower case;
- an access point is unique across the company: a repeat within the subscription is flagged in the field with “This value is already in use”, and an access point already used in another subscription is rejected by the server on saving — “Failed to save the subscription. Access points must be unique”;
- a row you add needs an office and at least one access point (“Specify at least one access point”);
- an event is assigned to the space picked in the row. If a floor is picked, reports show the floor, and the office filter of analytics counts the event only when that floor is inside the selected space;
- mappings are deleted together with the subscription. If an office is deleted, its row stays in the subscription: events for its access points arrive without an office, and the subscription can be saved again only after that row is removed.
Example: if your PACS sends Turnstile 1 in the office key and this access point is mapped to the “Berlin” office, the event is recorded with the Berlin office.
2. Send events — POST /api/scud/json/{token}
curl -X POST -H "Content-Type: application/json" -H "Un-Token: <access token>" \
https://acme.unspot.com/api/scud/json/3f2a...-connection-token \
-d '{
"space": "HQ Berlin",
"user": "jane.doe@example.com",
"status": "in_office"
}'The example uses the old key format — space, user and status, with no location key. With the default form settings the request body has to contain the keys office, location, email and status, otherwise the event is rejected with Invalid payload. Send the value HQ Berlin, which sits in space here, in the office key: it is an access point, and for the event to be assigned to an office it has to be mapped to that office in the subscription.
- User identification: if the user value is an email, the user is matched by email only, and no other method is tried when that misses. When the value does not look like an email, UnSpot tries the pass number, then the full name, then the display name — the display-name step was added on 7 September 2026. An ambiguous match at any step is rejected.
- The display-name match compares the whole string: leading and trailing spaces are trimmed, several spaces in a row count as one, and case is ignored —
" Anna Smith "finds the employee whose display name isAnna Smith. Unlike the full-name match it drops no words and does not try the reverse word order, and a single-word value is looked up as well. The rule is the same for JSON and for Sigur. - Status:
in_office— the employee came in,out_office— left; leading and trailing spaces and case are ignored. The event time is the moment UnSpot receives the request. - Events are processed asynchronously; each event (including errors) is recorded in the integration log (Reports → Integration history).
3. What UnSpot does with an event
- Marks the user as present in / absent from the office.
- Confirms check-in for the user’s bookings when check-in policies require office presence.
- Feeds office-attendance analytics and reports.
- Determines the office of the visit: the value of the office key is looked up among the access points of this subscription, ignoring case and leading or trailing spaces. If it matches, the office is written to the visit log; it shows in the Office column of the History of Office Visits (PACS) report and is taken into account by the office filter of PACS analytics. If it does not match or the value is empty, the event is still processed and the employee status changes, but the office in the log stays empty.
Errors
Integration not found— wrong endpoint token.Access to subscription denied— theUn-Tokenheader does not match the configured access token.Subscription deactivated— the subscription is switched off in UnSpot.User not found/Multiple users found by pass number— the user identifier could not be resolved unambiguously.Invalid payload— the body lacks one of the configured keys (office, location, user or status), or the user identifier is empty. The event is rejected and logged.
For a hands-on example of the JSON variant, see Incoming Webhooks: Connecting PACS via JSON.
