Skip to content
Petal

All help pages

Connect other tools: webhooks, the API and Zapier

1. What you can connect today

Open the account menu, choose Administration, then All integrations. It lists every tool PetalCRM connects to or will connect to, and says for each whether you can connect it now. Today you can connect Gmail, from Mail and calendar (connect your mailbox); Outlook, Google Calendar and Outlook Calendar are coming soon. The API and webhooks card has Set up, which opens the page where you create API keys and webhooks. The Claude and ChatGPT card has Set up too, which opens Connected AI tools. A tool marked Coming soon cannot be connected yet. While connecting Google accounts is paused, until Google finishes approving PetalCRM, the Gmail card says so instead of showing Connect (if there is no Google button).

2. Zapier

Zapier is listed as Coming soon. It cannot be connected from PetalCRM yet. When it can, it will ask for an API key and your workspace, the first part of your PetalCRM address.

3. API keys

An API key lets your own software, or a tool such as Zapier, use PetalCRM as you. It sees and changes only what you may. Changes made with a key that can change records take effect straight away, as if you made them. PetalCRM's own assistant never gets a key: what it suggests waits for you to approve it.

  1. Open Administration, then API and webhooks.
  2. In Name, give the key a name you will recognise, such as Zapier.
  3. Under What it can do, choose Read only or Read and change. Zapier triggers need only read; Zapier actions need read and change.
  4. Leave Can read the text of emails off unless the tool needs whole emails (reading an email's text). You cannot add it to a key later; create a new key instead.
  5. In Expires after, choose how long the key works: 90 days unless you pick 30, 180 or 365.
  6. Press Create key. You may be asked to sign in again first.
  7. The key is shown once. Press Copy, paste it where it is needed, then press I've saved it. It is not shown again. If you lose it, revoke it and create a new one.

We email you whenever a key is created, so you would know if someone else did it.

Your keys lists each key with the first characters that identify it, what it can do (a key that can read email text also says Reads email text), when it expires and when it was last used. To stop a key working, press Revoke beside it, then Revoke key. Anything using it stops at once, and it cannot be undone. Owners and administrators see every key in the workspace, under Keys in this workspace, and can revoke any of them, except that an administrator cannot revoke an owner's key.

4. Webhooks

A webhook tells your server when a deal, contact, organization, activity or lead you may see changes. It says which record changed, never what the record says. Each message is signed, so your server can check it came from PetalCRM.

  1. Open Administration, then API and webhooks.
  2. In Address to deliver to, give an https address your server listens on.
  3. Under Tell it about changes to, tick the kinds of record.
  4. To hear only some changes, tick events under Only tell it when (optional): a deal is created, a deal changes or moves stage, a deal is won, a deal is lost, a person is added, or an activity is marked done. An event is available once its kind of record is ticked. Tick none to be told about every change to those records.
  5. Press Add webhook. You may be asked to sign in again first.
  6. The signing secret is shown once. Press Copy, put it in your server, then press I've saved it. It is not shown again.

Your webhooks lists your webhooks, with each one's recent deliveries and their state. Delete one from the list when you no longer need it.

A webhook only ever tells you about records you can see. If your role changes, so does what it tells you.

5. Give a webhook a new signing secret

If a webhook's signing secret may have leaked, or you change it on a schedule, press New secret beside the webhook in Your webhooks. You may be asked to sign in again first. The new secret is shown once, the same way as when you added the webhook. For the next 24 hours each message is signed with both the old and the new secret, so you can switch your server over without missing one.

6. Reading an email's text

A key sees each email's sender, recipients, date and subject, but not its text. Notes, calls and meetings you typed in yourself are the exception: a key reads them as you wrote them.

To let your software read the text of emails, create a key with Can read the text of emails ticked (API keys). Your software then asks for one email at a time, by its id, and says it wants the text. It gets only emails you can open yourself in PetalCRM; an email you could not open answers the same as one that does not exist.

  • Each email text handed to a key is recorded: which key, which email and when, never the text itself.
  • For now, one key can read up to 30 email texts a minute and 1,000 a day, and all your keys together up to 2,000 a day. Past that, the answer is too many requests, with the time to try again.
  • Addresses that file mail into PetalCRM are hidden from a key wherever they appear, in an email's text or anywhere else.
  • When Zapier can be connected, it will not offer an email's text.
  • PetalCRM's own assistant cannot read an email's text this way.

7. Figures and the forecast, for an AI agent

An agent with a Read only key gets the figures a person sees, over the deals that person can see. Call run@1-style operations as API keys say. Operations: report.run (send {"definition": …}, one of the two below; money comes back in cents, per currency), report.saved.run, report.list, forecast.change.read ({"period": "this_quarter"}, or this_month, this_year) and activity.list ({"status": "open", "period": "all"}; by default only what is overdue or due today). A key that can change records also has report.definition.save.

Won deals this quarter, by owner:

  • {"language":1,"subject":"deal","filters":[{"field":"status","op":"eq","value":"won"}],"period":{"field":"closed_on","range":{"relative":"this_quarter"}},"measure":{"fn":"value"},"view_by":{"field":"owner"}}

Open pipeline value, with no period:

  • {"language":1,"subject":"deal","filters":[{"field":"status","op":"eq","value":"open"}],"measure":{"fn":"value"}}

A key cannot export, and cannot create or change a dashboard. A tool connected over MCP reads, and changes only what your workspace's owner or admin allows (Connect your AI tool).