Webhooks

Polling the visitor list every minute works, but a webhook is better: Vizito calls your endpoint as the event happens, and you do nothing in between.

Webhooks are part of the Enterprise plan. On Standard and Pro the configuration endpoints answer 404 and no events are delivered.

Configure the endpoint

One webhook per location, set either on the Integrations page in the Backoffice or through the API:

cURL

curl -X POST https://api.vizito.eu/api/companies/{company_id}/webhooks \
  -H "Authorization: Bearer $VIZITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/vizito",
    "http_method": "POST",
    "auth_username": "vizito",
    "auth_password": "a-shared-secret",
    "enabled": true
  }'

Response

{ "message": "Webhook configured successfully", "webhook_id": "66c2b3c4d5e6f70011223344" }

http_method may be POST, PUT, PATCH or GET. With POST, PUT and PATCH the event is the JSON body; with GET it is the query string. If you set auth_username and auth_password, Vizito sends them as HTTP Basic credentials on every call — the simplest way to prove the call came from Vizito.

What you receive

{
  "eventName": "visitor_signed_in",
  "companyId": "5f2a1b9c4d3e2f0011223344",
  "visitorId": "66b0f1a2c3d4e5f600112233",
  "visitTypeId": "5f2a1b9c4d3e2f0011223399",
  "knownVisitorId": "66c1a2b3c4d5e6f700112233"
}

The payload is deliberately thin: it names what happened and to which object, not the object itself. Fetch what you need with the ids — GET /visitors/{visitorId} gives you the whole visit, photo and signature included.

Events

Event	Extra fields	Fires when
`visitor_signed_in`	`visitorId`, `visitTypeId`, `knownVisitorId`	A visit starts, from any source
`visitor_signed_out`	`visitorId`, `visitTypeId`, `knownVisitorId`	A visit is closed
`visitor_updated`	`visitorId`, `visitTypeId`, `knownVisitorId`	A visit’s details change
`visitor_screening_approved`	`visitorId`, `knownVisitorId`, `approvalStatus`	A host approves a screened visitor
`visitor_screening_rejected`	`visitorId`, `knownVisitorId`, `approvalStatus`	A host rejects a screened visitor
`registered_visitor_created`	`knownVisitorId`, `visitTypeId`	A registered visitor is added
`registered_visitor_updated`	`knownVisitorId`, `visitTypeId`	A registered visitor changes
`registered_visitor_deleted`	`knownVisitorId`, `visitTypeId`	A registered visitor is removed
`registered_visitor_preregistered`	`knownVisitorId`	An invited visitor completes their pre-registration
`device_added`	`deviceUuid`	A kiosk is activated
`device_online` / `device_offline`	`deviceUuid`	A kiosk connects or drops off
`device_deleted`	`deviceUuid`	A kiosk is removed
`company_updated`	—	The location’s configuration changes

Delivery rules

Failures are counted, and five in a row disables the webhook

Every delivery error — a timeout, a non-2xx answer, an unreachable host, an invalid URL — increments a counter. At five consecutive failures the webhook is switched off and the location’s global admins are emailed the last error, so a dead endpoint does not silently swallow events forever. One successful delivery resets the counter to zero.Re-enable it on the Integrations page or by posting the configuration again — saving it clears the failure count.

There are no retries

A failed delivery is not retried. Answer quickly with a 2xx and do your work asynchronously; if your endpoint is down, reconcile afterwards by reading the visitor list.

Answer fast

Events are delivered as they happen and your response time is on the critical path of somebody standing at a kiosk. Acknowledge first, process later.

Reading the current configuration

curl https://api.vizito.eu/api/companies/{company_id}/webhooks \
  -H "Authorization: Bearer $VIZITO_API_KEY"

Returns the enabled webhook, or {} when there is none. An auto-disabled webhook reads as {} too — which is the quickest way to check whether yours is still alive.

Get started

Guides

Configure the endpoint

What you receive

Events

Delivery rules

Reading the current configuration

​Configure the endpoint

​What you receive

​Events

​Delivery rules

​Reading the current configuration

Configure the endpoint

What you receive

Events

Delivery rules

Reading the current configuration