API keys and webhooks

Scopes, expiry, IP allow list, signed deliveries.

Vintage People has a public API and outgoing webhooks for linking your own systems. Both are set up in Settings, Integrations by someone with settings access.

API keys. Create a key with a name and a scope. A read key only reads; a read and write key can also create and change records through the public API. Every key expires, after 12 months by default and never later than two years, and you can set a date to rotate it by. To limit where a key can be used, enter the allowed source addresses as CIDR ranges, for example 203.0.113.0/24. The key is shown once, so store it safely. Keys are rate limited, and you can revoke one at any time.

The public API covers employees (read and create), payroll runs (read) and biometric punches. Ask us for the API reference.

Webhooks. Subscribe an HTTPS address to events from the event list. For example, employee.created fires however an employee is created (added, imported, migrated, hired, through the API or cloned), and employee.updated fires for profile, employment, statutory and pay currency changes.

Each delivery is signed with HMAC-SHA256 in the X-VP-Signature header, with the event name in X-VP-Event, so your system can check it came from us. Failed deliveries are retried with a growing delay, up to five attempts. Addresses on private or internal networks are refused, and redirects are not followed.

Related articles