Build an app
Webhooks for apps
On this page
Declare webhooks in the manifest and every company that installs your app gets an endpoint for it: Bizisy sends that company's events you subscribed to, to your url, signed with a secret of that install. Payloads, headers, retries and signatures are the same as for any webhook endpoint.
An event needs the scope of its area: person.*, member.* and approval.* need people:view; position.* positions:view; checklist.* checklists:view; document.* documents:view; pay_report.* pay_equity:view; payroll.* payroll:view. Structure and job title events need none. The install receives only the events its consented scopes cover.
Get the signing secret#
Right after the token exchange, call:
curl -X POST https://api.bizisy.com/v1/platform/app_installs.webhook_secret.issue \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'content-type: application/json' -d '{}'{ "data": { "endpoint_id": "01k…", "secret": "whsec_…" } }The secret is returned once: store it with the install. Call it again any time to rotate: for overlap_hours (default 24, at most 72; 0 stops the old one at once) every request is signed with both. Until you issue it, the endpoint signs with a random secret nobody knows; deliveries made meanwhile are retried, and signed with your secret once you have it.
Verify every request with it, and tell installs apart by the organization_id in each payload.
What companies see#
The endpoint appears in the company's Integrations → Webhooks, marked as yours. They can turn it off and on; its address, events and secret come from your app. It is deleted when they uninstall your app, and its deliveries wait while Bizisy has your app suspended. Events carry ids and the public and job details of the record, never private details or pay.
Something missing or wrong on this page? Write to hello@bizisy.com.