The API and webhooks are included in the Growth and Pro plans, and in your free trial. Starter doesn't include them. You manage everything on one page, Settings › API & webhooks.
API keys
- Go to Settings › API & webhooks.
- Under API keys, type a name (for example Zapier) and choose Create key.
- Copy the key straight away. It starts with
crm_live_. You can't see it again.
The list shows each key's name and when it was last used. Revoke switches a key off for good.
- Only owners and admins can create or revoke keys.
- A key acts as the person who created it, with that person's permissions. If they leave the workspace, the key stops working. If your workspace requires two-step sign-in, the key won't work until its creator has set it up.
- Send keys only in the
Authorizationheader. A request withapi_tokenin the address is refused.
The REST API
The API lives at your ZyfrHub address followed by /api/v1. Every request needs the header Authorization: Bearer <your key>. To check a key works, ask for the workspace it belongs to:
curl https://YOUR-ZYFRHUB-ADDRESS/api/v1/me \
-H "Authorization: Bearer crm_live_xxxxxxxx"
The page shows your exact address above the keys. Replies are JSON like { "success": true, "data": … }. Lists add a meta section, and limit and offset page through them. Errors return "success": false and a message.
The API covers opportunities, contacts, organisations, leads, activities, notes, products, pipelines, custom fields, sales orders and tickets. Every path is described at /api/v1/openapi.json on your ZyfrHub address.
Each key can make 1,200 requests a minute. Beyond that you'll get a "Rate limit exceeded" reply.
Webhooks
A webhook sends a message to your address whenever something changes in ZyfrHub.
- Under Webhooks, enter the address that should receive the messages. It must be a public https address.
- Choose the events you want. Leave all of them unselected to receive every event.
- Choose Add webhook.
Verify the address first
Nothing is sent to a new webhook until you've shown the address is yours. ZyfrHub sends a webhook.verification message containing a challenge starting with zv_. Either:
- reply with HTTP 200 and exactly
{"challenge":"<the challenge>"}, or - paste the challenge your endpoint received into the Challenge box and choose Verify.
The challenge is good for 24 hours. Choose Send a new challenge if it has expired (up to five an hour).
What gets sent
Each message is JSON with an id, the event name, occurredAt and the record details under data. The events are:
- Opportunities: created, updated, stage_changed, won, lost, deleted
- Contacts, organisations and activities: created, updated, deleted
- Email: received, sent, opened, clicked
- Leads: created, converted
- Quotes: accepted, declined, paid, approval_requested, approval_decided
- Bookings: created, rescheduled, cancelled
- Customer service: ticket created, updated, solved, and survey responded
- Sales orders: created, confirmed, signature_requested, viewed, signed, declined, handed_over, fulfilled, amended, cancelled
On the page they're written in full, such as opportunity.won.
Checking a message is really from ZyfrHub
Every message carries these headers: x-crm-event, x-crm-delivery, x-crm-timestamp and x-crm-signature. To check the signature, work out an HMAC-SHA256 of the timestamp, a full stop and the raw message body, using the webhook's secret. It should equal the signature after sha256=. Reject messages with a timestamp more than five minutes old. Copy the secret from the webhook's row in the list.
Retries and the delivery log
Any 2xx reply counts as received. If your address is down or replies with anything else, ZyfrHub tries again after 1 minute, then 2, 4 and so on, up to 8 attempts in all, before marking it failed. The table under the webhooks list shows the latest 20 deliveries with their status, reply code and number of attempts. Only owners and admins see webhooks and the log.
Zapier and Make
Both tools can call web addresses and receive them, so the pieces above are all you need:
- Send data into ZyfrHub: use a web request step (such as Webhooks by Zapier, or the HTTP module in Make) pointed at an API path, with your key in the
Authorizationheader. - React to something in ZyfrHub: make a webhook step in Zapier or Make to get an https address, add it under Webhooks, then use the challenge it receives to verify it.
The ZyfrHub app for Zapier
We're getting an official ZyfrHub app listed in Zapier. Until it's approved you can connect Zapier with a webhook and an API key as described above. Once it's listed you'll choose ZyfrHub in Zapier, paste an API key, and pick from ready-made triggers (new lead, contact, organisation or opportunity, opportunity won or lost) and actions (create a lead, contact, organisation, task or note, and find a contact). It needs a Growth or Pro plan, or your trial, and an owner or admin's API key.