Webhooks

Webhooks tell your system when something changes in Bizisy, usually within a minute, so you don't have to poll. Someone is hired, changes job or leaves; a team is created; a document is added: Bizisy sends a signed HTTPS POST to your endpoint.

Set up an endpoint#

1. In Bizisy, an owner or admin opens Manage → Settings → Webhooks and adds an endpoint: its HTTPS URL, an optional description and the event types it receives.
2. Bizisy shows the endpoint's signing secret (whsec_…) once. Store it with your receiver.
3. Press Send test event to get a webhook.test event, signed like any other.

Only changes made after an endpoint is added are sent. A company has at most 10 endpoints.

Adding an endpoint, changing its URL, adding events, turning it on, rolling its secret and deleting it happen in the app, signed in as an owner or admin; every owner and admin is emailed when an endpoint is added or starts sending to a new host. API keys and AI assistants can list endpoints, read the delivery log, send test events, resend deliveries, remove events and turn an endpoint off (Webhook endpoints).

What we send#

An HTTPS POST with a JSON body:

POST /your/endpoint HTTP/1.1
content-type: application/json
user-agent: Bizisy-Webhooks/1
webhook-id: msg_01k6w4d2c3b0e9f8a7g6h5j4k3
webhook-timestamp: 1791194400
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"type":"person.hired","timestamp":"2026-10-05T10:00:00.000Z","data":{"organization_id":"01k5…","person_id":"p1","start_date":"2026-11-02","person":{"id":"p1","name":"Bea Santos","title":"Product Designer",…}}}

Headers follow Standard Webhooks.

Snapshots: public and job details only#

Snapshots hold what an HR API key would see: the public and job tiers. Never private details (personal contact, address, birthday, emergency contacts, payroll identifiers) and never pay (visibility tiers). Document events carry ids only, never a title, file name or category. Fetch anything else with the API.

Snapshots are current, not historical. The ids, dates and timestamp describe the change; the snapshot is filled in when each attempt is sent. If someone is hired and renamed a minute later, both notices show the new name, and a retry or resend shows the record as it is then. A record erased since then shows as null.

Order and duplicates#

• No ordering guarantee. Deliveries can arrive out of order, especially after retries. Order by timestamp, or fetch the current state with the API.
• At least once. The same message can arrive more than once (a retry after a timeout, a resend). Skip a webhook-id you already processed.

Next#

• Verify signatures in Node, Python or Go.
• Retries and failures: what counts as a failure, the schedule, automatic turn-off.
• Best practices, and the sync guide for a complete integration.