View Categories

How to Use Webhooks and API Keys

Incoming webhooks let other apps send events to OneSuite that create, update or delete clients, CRM companies, people and opportunities. API keys give another system full access to OneSuite’s API for your business. Together they let you connect forms, no-code tools such as Make, Zapier or n8n, and your own code without typing the same records twice.

In this guide you’ll learn how to:

  • Create an incoming webhook and find its URL and secret
  • Send a correctly formatted event to OneSuite
  • Check the events a webhook has received
  • Generate, pause and delete API keys
  • Keep your webhook secrets and API keys safe

Before you start

  • Open Settings from the account menu: click your name at the bottom of the sidebar, then Settings.
  • Incoming Webhooks (under Integrations) and API Keys (under Workspace) need access to your business’s admin settings. If you can’t see them, ask an admin.
  • OneSuite only receives webhooks. It has no outgoing webhooks, so it can’t send events to your app.

How to create an incoming webhook

You create a webhook by giving it a name and choosing whether it works on clients or CRM records.

  1. Open Settings, Integrations, Incoming Webhooks.
  2. Click Create Webhook.
  3. Enter a Name, for example Zapier Integration.
  4. Choose the Module: Client for client records, or CRM for companies, people and opportunities.
  5. Add a Description if you want to note what the webhook is for.
  6. Click Create Webhook.

OneSuite opens the new webhook’s page, with the tabs Overview, API Reference, Events and Integrations.

Incoming webhook Overview tab showing the Webhook URL, the masked Secret with its eye, copy and Regenerate controls, and the Authentication box

What the webhooks list shows

The Incoming Webhooks page lists every webhook with its Name, Status (Active or Inactive), Events counts (Received, Success, Failed) and Last Received time. Cards above the list show Total Webhooks, Active Webhooks, Total Events Received and Success Rate. Each row’s Actions menu has View, Edit and Delete.

How to find the webhook URL and secret

The webhook’s URL and secret are on its Overview tab, under Endpoint & Authentication.

  1. Open the webhook from the list with View.
  2. On Overview, copy the Webhook URL with the copy button. This is the address your other app sends events to.
  3. Under Secret, click the eye icon to show the secret, or the copy button to copy it. The secret is masked until you show it.

Send these two headers with every request:

Content-Type: application/json
X-Webhook-Signature: <webhook_secret>

Use the exact secret shown on the Overview tab as the value of X-Webhook-Signature. The Overview tab also shows Statistics for the Last 30 days.

How to regenerate a webhook secret

You regenerate a secret with Regenerate on the Overview tab. The current secret stops working straight away.

  1. On the Overview tab, click Regenerate next to Secret.
  2. Read the warning, then tick I understand that the current secret will be invalidated and I need to update my external service immediately.
  3. Click Regenerate Secret.
  4. Copy the New Secret and update every app that sends to this webhook. Requests that still send the old secret fail.
  5. Click Done.

Which events can a webhook receive?

A webhook receives the events for its module: three for Client and nine for CRM. The API Reference tab lists them with example payloads you can copy.

Module Event type What it does Required fields
Client client.create Creates a client name, email
Client client.update Updates a client client_id or external_id
Client client.delete Deletes a client client_id or external_id
CRM company.create Creates a company name
CRM company.update Updates a company company_id or external_id
CRM company.delete Deletes a company company_id or external_id
CRM people.create Creates a person name, email
CRM people.update Updates a person people_id or external_id
CRM people.delete Deletes a person people_id or external_id
CRM opportunity.create Creates an opportunity name
CRM opportunity.update Updates an opportunity opportunity_id or external_id
CRM opportunity.delete Deletes an opportunity opportunity_id or external_id

How to format a webhook payload

Each payload is a JSON object that names its event in event_type and carries the record’s fields.

  • event_type names the event, such as client.create or opportunity.create. Every payload must include it.
  • event_id is optional and is used for idempotency. Event Details on the Events tab shows whether an event was a Duplicate.
  • For CRM webhooks, you can put the record’s fields inside a data object or at the top level of the payload.
  • For client webhooks, type is optional and defaults to company. Use individual for a person.
  • The API Reference tab lists every field key you can send for the webhook’s module, with a copy button for each.

This is the example opportunity.create payload from the API Reference tab:

{
  "event_id": "evt_opp_1",
  "event_type": "opportunity.create",
  "name": "Enterprise Deal Q1",
  "amount": 50000,
  "currency": "USD",
  "close_date": "2025-03-31"
}

How to check the events a webhook received

The Events tab lists what the webhook has received, under Recent Events.

  1. Open the webhook and click Events.
  2. Find the event by its Event ID, Type, Status, Action or Received At time.
  3. Click the view icon to open Event Details.

Event Details shows the Processing Status, the Action Taken, the Signature Status (Valid or Invalid), whether the event was a Duplicate, any Error Message, and the Payload and Headers that arrived.

How to connect Google Forms

The Integrations tab has a step-by-step guide that sends Google Form submissions to the webhook.

  1. Open the webhook and click Integrations.
  2. Click Google Forms.
  3. Work through 1. Prerequisites. The webhook must be active, and you need owner or editor access to the form.
  4. In 2. Map Form Questions to Fields, choose what you want to create if asked, then match each exact question title in your form to a OneSuite field.
  5. In 3. Copy the Generated Script, copy the script.
  6. In 4. Install in Google Forms, follow the steps to paste the script into Apps Script, select createTrigger in the function dropdown, click Run, and authorize the script.
  7. Submit a test response in your form and check that it arrives on the Events tab.

How to pause, edit or delete a webhook

Use the switch on the webhook’s page to make it Active or Inactive, and the list’s Actions menu to edit or delete it.

  • Pause: open the webhook and turn the switch off. The status changes to Inactive.
  • Edit: click Edit on the webhook’s page or in the list, change the Name, Module or Description, and click Update Webhook.
  • Delete: in the list, open Actions, click Delete and confirm.

How to generate an API key

You generate an API key in Settings, Workspace, API Keys with Generate new key.

  1. Open Settings, Workspace, API Keys.
  2. Click Generate new key.
  3. Enter a Key Name so you know what the key is for.
  4. Leave Key Status set to Active.
  5. Click Generate.

An API key gives full access to OneSuite’s API for your business. Keys have no scopes, so you can’t limit a key to certain records or actions.

How to see and copy an API key

Each key’s card shows its name, its status and the first 3 characters of the key. Click Show to see the full key and Hide to mask it again. Click Copy, or click the key itself, to copy it. You can show and copy a key at any time.

How to pause or delete an API key

Set a key to Inactive to pause it, or delete it to remove it for good.

  • Pause: open the key’s menu, click Edit Key, set Key Status to Inactive and click Update.
  • Rename: use Edit Key and change the Key Name.
  • Delete: open the key’s menu, click Delete Key and confirm.

Keeping secrets and keys safe

Treat every webhook secret and API key like a password, because anyone who holds one can act on your business’s data.

  • Store them in your other tool’s secure settings, never in shared documents or public code.
  • If a webhook secret leaks, click Regenerate straight away and update the apps that use it.
  • If an API key leaks, delete it and generate a new one.
  • Set keys and webhooks you no longer use to Inactive, or delete them.
  • Give each app its own key and webhook, so you can pause one without breaking the others.

Not using OneSuite yet? Start your free trial →

FAQs

Can OneSuite send webhooks to my app?

No. OneSuite only has incoming webhooks, which receive events from other apps; it doesn’t send outgoing webhooks.

What headers does a OneSuite incoming webhook need?

It needs Content-Type: application/json and X-Webhook-Signature set to the webhook’s secret. Copy the secret from the webhook’s Overview tab.

Why is my webhook showing failed events?

Open the Events tab and view the event. Event Details shows the Signature Status, which tells you whether the secret matched, plus the Error Message and the payload that arrived.

Can I limit what an API key can access?

No. Every API key has full API access and there are no scopes. Give each app its own key and delete any key you no longer need.

Can I just import a spreadsheet instead of using webhooks?

For a one-off batch, an import works well. A webhook suits records that keep arriving from another tool, because each new form entry or deal reaches OneSuite on its own.

What to do next

See all integrations: Compare every tool OneSuite connects to in Integrations Overview.

Import records in bulk: Bring in existing clients and contacts with Imports, Exports, and Search.

Know your CRM records: See how companies, people and opportunities connect in How Opportunities, Companies, and People Work Together.

Updated on October 1, 2026