Outgoing webhooks API reference

Outgoing webhooks let UnSpot notify your systems about events in real time: UnSpot sends an HTTPS POST with a JSON payload to a URL you configure. Typical use case: passing parking bookings to a security or gate-control system.

Setting up a webhook

Go to Manage > Integrations > Outgoing webhooks and click “Create outgoing webhook”. A name and an event are always required; the rest of the form depends on the event type. The event cannot be changed afterwards — the field is locked when you edit a subscription.

• API-type events send an HTTPS request: they need a recipient URL and the spaces the subscription applies to. Only events from the selected spaces are delivered. A subscription with the same event and URL cannot be created twice.
• Email-type events send an email. The recipient is picked in the “Recipient” field from the list of employees — an internal, active UnSpot user rather than an arbitrary address. Typing an address by hand is no longer possible; the field placeholder reads “Select recipient”. Two subscriptions to the same event with the same recipient cannot be created.
• The locker email events additionally require the spaces (multi-select, mandatory), and “Locker booking exceeds X days” also asks for the “Number of days” field: an integer from 1 to 365, 1 by default.

What happened to the old email recipients. The recipient used to be an arbitrary email address; it is now a reference to a UnSpot user. During the migration the address is matched against employees by email, case-insensitively: if an active employee is found, they become the recipient; if none is found, or the employee is archived, deleted or deactivated, the recipient stays empty and the subscription is switched to “Disabled”. In the subscription list such a row shows “Recipient not specified” instead of a recipient, and it cannot be switched on: the server answers with “Failed to update the subscription status. Recipient is not specified.” To bring the subscription back, open “Edit”, pick a recipient and save. The same mechanism keeps working later: if the recipient is archived, deleted or deactivated by provisioning, the subscription loses its recipient and is disabled again.

Events

HTTPS (API-type) events:

Email-type events send a message to the selected recipient and make no HTTPS request — the payload and delivery rules below do not apply to them.

The two locker subscriptions were added on 7 September 2026. “Booking canceled” emails the recipient when the booking horizon policy removes a cell booking; it is sent only for subscriptions whose selected spaces include the locker office, and the booking owner receives a separate email of their own. “Locker booking exceeds X days” sends one email per subscription listing every cell that qualified.

Mind the wording “exceeds X days”. The email is sent on the day the booking term equals the configured number of days, not every day while it is over that number: the comparison is for equality, not for exceeding the value. The letter X in the subscription name is part of the label, not a placeholder for the number. Days are counted in the time zone of the locker office, or the company time zone when the office has no settings of its own.

Payload format

All parking events share the same base payload; action tells them apart:

POST <your URL>
Content-Type: application/json

{
  "fullName": "Jane Doe",
  "email": "jane.doe@example.com",
  "vehicleNumber": "AB-123-CD",
  "vehicleModel": "Tesla Model 3",
  "start": "2026-07-08T09:00:00+00:00",
  "end": "2026-07-08T18:00:00+00:00",
  "office": "HQ Berlin",
  "parkingPlace": "P-12",
  "action": "Created",
  "bookingType": "Parking"
}

POST <your URL>
Content-Type: application/json

{
  "fullName": "Jane Doe",
  "email": "jane.doe@example.com",
  "vehicleNumber": "AB-123-CD",
  "vehicleModel": "Tesla Model 3",
  "start": "2026-07-08T09:00:00+00:00",
  "end": "2026-07-08T18:00:00+00:00",
  "office": "HQ Berlin",
  "parkingPlace": "P-12",
  "action": "Created",
  "bookingType": "Parking"
}

Delivery, timeouts and retries

• Requests are sent as POST with Content-Type: application/json and a 240-second timeout.
• Respond with any 2xx status to acknowledge delivery.
• Failed deliveries increment a failure counter; delivery is retried by the queue. After 100 consecutive failures the webhook is switched to the failed status and administrators are notified. A successful delivery resets the counter.
• Webhook health is visible in External API > monitoring (webhooks category) and in the Integrations page.

Security recommendations

• Standard webhook requests carry no authentication header — treat the endpoint URL as a secret: use HTTPS and include a random path segment (e.g. https://example.com/hooks/unspot-8f3a91).
• Validate the payload structure and restrict your endpoint to expected fields.
• For the Claris integration, UnSpot sends its own Authorization: Bearer token and an extended payload — enable the Claris option only for that system.

For a practical walkthrough of the parking use case, see Outgoing Webhooks: Parking place booking notifications.