Outgoing webhooks API reference

Outgoing webhooks notify you about UnSpot events in two ways. API-type events send an HTTPS POST with a JSON payload to a URL you configure, at the moment of the event; email-type events send an email to a selected employee, and some of them are sent by a scheduled run rather than at the moment of the event. Typical API 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” and “Locker has not been used for more than X days” also ask 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 format and the delivery rules in the “Payload format” and “Delivery, timeouts and retries” sections do not apply to them.

Locker subscriptions: the first two 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.

A third locker subscription was added on 21 September 2026. “Locker has not been used for more than X days” reports bookings that have been held for longer than the period set without the cell being opened once: a cell qualifies when it was booked earlier than “today minus N days” and has not been opened at any point in that period. Days are counted in the time zone of the locker office, or the company time zone when the office has none of its own. One email is sent per subscription — the subject is “Unused lockers detected” and the body lists the qualifying cells as “locker, cell” with links to the lockers section; no email is sent when nothing qualifies. Unlike the neighbouring duration event, this email arrives on every run of the mailer until the cell is opened. The subscription only works with the Pocket Lock integration connected: the sign of use is the cell actually being opened, and that is what the integration reports.

Mind the letter X in the locker subscription names. In both “Locker booking exceeds X days” and “Locker has not been used for more than X days” the letter X is part of the label, not a placeholder for the number — the actual value is set in the “Number of days” field. The duration 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.

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.
• A failed delivery is retried by the queue — up to 10 retries, 10 seconds apart. The failure counter increases on every attempt, retries included, so one undeliverable event adds 11 to it. At 100 failures the webhook is switched to the failed status. A notification email is then sent — not to “administrators”, but to the recipients of active system_warning (“Synchronisation issues”) subscriptions; with no such subscription, nobody is notified. The same email is sent when a subscription is switched off manually. A successful delivery resets the counter, and so does switching a failed webhook back on manually.
• 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 a practical walkthrough of the parking use case, see Outgoing Webhooks: Parking place booking notifications.