# API keys and webhooks

> Give other systems access to the Clockwork CRM API, and send them events as they happen.

Source: https://help.clockworkcrm.com/admin/api-and-webhooks
Last updated: 2026-09-30

API keys let another system use the Clockwork CRM API. Webhooks send another system a message when
something happens in Clockwork CRM. Both are managed by administrators.

**API Documentation** in the administration portal's top bar, and in **Administrator Tools**, opens
the developer documentation for the API.

## API keys

**Administrator Tools → API Keys** lists every API key.

| Column | What it shows |
|---|---|
| **Name** | The key's name |
| **Type** | **Manual** for a key created here. An app a user has signed in to, such as an AI assistant, shows the app's name. A key used by a plugin shows the plugin's name |
| **User Scope** | The user the key acts as, or **Not scoped** |
| **Last Modified** | When the key was last changed |
| **Last Modified By** | Who last changed it |
| **Created By** | Who created it |

The filters at the top narrow the list:

| Filter | What it does |
|---|---|
| **Type** | **All**, **Manual**, **OAuth** (keys created when a user signs in to an app) or **Plugin** |
| **User scope** | **All users**, **Not scoped**, or one user |
| **Search for API keys** | Finds keys by name |

### Adding an API key

1. Click **Add API Key**.
2. Enter an **API Key Name**. Each key needs a different name.
3. Optionally choose a **User Scope (optional)**.
4. Click **Save**.
5. Open the key's actions menu and click **Manage Permissions** to choose what it can do. A new key
   has no permissions.

![The Add API Key form](https://clockworkcrm.blob.core.windows.net/public-internal/docs/admin/admin-api-key-form.png?v=2f3b8a53)

| Field | What it does |
|---|---|
| **API Key Name** | The key's name. Required |
| **User Scope (optional)** | The user the key acts as when the API checks what a user can see. **None - No user scope** leaves it unscoped |

A key with a user scope acts as that user wherever the API checks what a user can see. For example,
it can read the email in that user's own accounts. A key with no user scope is not limited to one
user.

### A key's actions

Each key's actions menu has:

| Action | What it does |
|---|---|
| **Manage Permissions** | Chooses which parts of the API the key can use. Not available for plugin or OAuth keys |
| **View Key** | Shows the key. Hold the eye button to reveal it, and use the copy button to copy it |
| **Edit** | Changes the name and user scope. Not available for OAuth keys |
| **Delete** | Deletes the key. Anything using it stops working. For an OAuth key this is **Revoke**. Not available for plugin keys |

**Bulk Delete** deletes every ticked key.

**Regenerate API Key** in **View Key** replaces the key with a new one. The old key stops working
straight away, so every system using it must be given the new key.

An OAuth key takes its permissions from what the user approved when they signed in to the app. A
plugin key is managed by its plugin. See [Connecting an AI assistant](https://help.clockworkcrm.com/general/ai-assistants) and
[Plugins](https://help.clockworkcrm.com/admin/plugins).

### Permissions

**Manage Permissions** lists the permissions in groups. Tick a permission to give it to the key, or
tick a group's box to give the key the whole group. **Filter permissions** finds a permission by
name. Click **Save** to keep your changes.

| Group | Permissions |
|---|---|
| **Person** | <ul><li>Read General Person Information</li><li>Write General Person Information</li><li>Delete Person Records</li><li>Read Person Notes</li><li>Write Person Notes</li><li>Read Person Timeline</li></ul> |
| **Company** | <ul><li>Read General Company Information</li><li>Write General Company Information</li><li>Delete Company Records</li><li>Read Company Notes</li><li>Write Company Notes</li><li>Read Company Timeline</li><li>Read Company Employees</li></ul> |
| **User** | <ul><li>Read Users</li></ul> |
| **Resource** | <ul><li>Read Resources</li><li>Write Resources</li><li>Delete Resources</li></ul> |
| **Case** | <ul><li>Read General Case Information</li><li>Write General Case Information</li><li>Delete Case Records</li><li>Read Case History</li><li>Read Case Comments</li><li>Write Case Comments</li><li>Read Case Files</li><li>Write Case Files</li><li>Read Case Types</li><li>Write Case Types</li><li>Read Case Statuses</li><li>Write Case Statuses</li><li>Read Custom Case Fields</li><li>Write Custom Case Fields</li></ul> |
| **Project** | <ul><li>Read Project Objects</li><li>Write Projects and Task Lists</li><li>Read Project Task Lists</li><li>Read Project Tasks, Including comments and logged time</li><li>Write Tasks, Comments and Time Logs</li><li>Read Project Files</li></ul> |
| **Automations** | <ul><li>Trigger Automations</li></ul> |
| **Email Accounts** | <ul><li>Read Emails, Accounts and Folders</li></ul> |
| **Email Sending** | <ul><li>Send Email (Uses Credits)</li></ul> |
| **Service** | <ul><li>Read Services</li><li>Write Services</li><li>Delete Services</li></ul> |
| **Tax** | <ul><li>Read Tax Rates</li><li>Write Tax Rates</li><li>Delete Tax Rates</li></ul> |
| **Sale** | <ul><li>Read Sale Records</li><li>Write Sale Records</li><li>Delete Sale Records</li></ul> |
| **Telephony** | <ul><li>Read Phone Numbers</li><li>Read Call History</li><li>Read Call Transcriptions</li><li>Read SMS History</li><li>Send SMS (Uses Credits)</li></ul> |
| **Calendar** | <ul><li>Read Calendar Activities</li><li>Write Calendar Activities</li><li>Delete Calendar Activities</li></ul> |
| **Knowledge Base** | <ul><li>Read Knowledge Base Articles</li></ul> |
| **Marketing** | <ul><li>Read Forms and Submissions</li><li>Read Landing Pages and Views</li><li>Read Sequences</li><li>Read Bulk Email Shots</li></ul> |
| **Product** | <ul><li>Read Products</li><li>Write Products</li><li>Delete Products</li></ul> |
| **Webhooks** | <ul><li>Manage Webhooks</li></ul> |
| **Tags** | <ul><li>Read Tags</li><li>Write Tags</li></ul> |
| **File Browser** | <ul><li>Write File Browser (Create Folders, Upload)</li></ul> |
| **Website Analytics** | <ul><li>Read Website Analytics</li></ul> |

**Manage Webhooks** lets the key create and remove webhook subscriptions. Installed plugins can add
their own groups to this list.

## Webhooks

A webhook sends a message to another system each time a chosen event happens in Clockwork CRM.
**Administrator Tools → Webhooks** lists them.

| Column | What it shows |
|---|---|
| **Name** | The webhook's name |
| **URL** | Where events are sent |
| **Events** | How many events it sends |
| **Active** | Whether it is sending events |
| **Last Updated** | When it was last changed |

Webhooks created through the API, such as those Zapier creates for its triggers, are listed here
too.

### Adding a webhook

1. Click **Add Webhook**.
2. Enter a **Name** and the **Endpoint URL**.
3. Enter a **Signing Secret**, or click **Generate** to create one.
4. Leave **Active** on. It is on for a new webhook.
5. Under **Events**, tick the events to send.
6. Click **Save**. It is not available until at least one event is ticked.

![The Add Webhook form: name, endpoint, signing secret, and the events to send](https://clockworkcrm.blob.core.windows.net/public-internal/docs/admin/admin-webhook-form.png?v=e9037137)

| Field | What it does |
|---|---|
| **Name** | The webhook's name. Required |
| **Endpoint URL** | The address events are sent to. Required |
| **Signing Secret** | Used to sign each event, so the receiving system can check it came from Clockwork CRM. Leave it empty to send events unsigned |
| **Active** | Whether events are sent. Events that happen while it is off are not sent later |
| **Events** | The events to send. Tick a group's box to send every event in it. **Filter events** finds an event by name |

Each webhook's actions menu has **Edit**, **Delete** and **Delivery Log**. **Bulk Delete** deletes
every ticked webhook.

### Events
| Group | Events |
|---|---|
| **Person** | <ul><li>Person created (<code>PersonCreated</code>)</li><li>Person updated (<code>PersonUpdated</code>)</li><li>Person deleted (<code>PersonDeleted</code>)</li><li>Person tag added (<code>PersonTagAdded</code>)</li><li>Person tag removed (<code>PersonTagRemoved</code>)</li><li>Person note created (<code>PersonNoteCreated</code>)</li><li>Person note updated (<code>PersonNoteUpdated</code>)</li><li>Person note deleted (<code>PersonNoteDeleted</code>)</li></ul> |
| **Company** | <ul><li>Company created (<code>CompanyCreated</code>)</li><li>Company updated (<code>CompanyUpdated</code>)</li><li>Company deleted (<code>CompanyDeleted</code>)</li><li>Company tag added (<code>CompanyTagAdded</code>)</li><li>Company tag removed (<code>CompanyTagRemoved</code>)</li><li>Company note created (<code>CompanyNoteCreated</code>)</li><li>Company note updated (<code>CompanyNoteUpdated</code>)</li><li>Company note deleted (<code>CompanyNoteDeleted</code>)</li></ul> |
| **Case** | <ul><li>Case created (<code>CaseCreated</code>)</li><li>Case updated (<code>CaseUpdated</code>)</li><li>Case deleted (<code>CaseDeleted</code>)</li><li>Case comment created (<code>CaseCommentCreated</code>)</li><li>Case comment updated (<code>CaseCommentUpdated</code>)</li><li>Case comment deleted (<code>CaseCommentDeleted</code>)</li><li>Case tag added (<code>CaseTagAdded</code>)</li><li>Case tag removed (<code>CaseTagRemoved</code>)</li><li>Case file created (<code>CaseFileCreated</code>)</li><li>Case file deleted (<code>CaseFileDeleted</code>)</li></ul> |
| **Sale** | <ul><li>Sale created (<code>SaleCreated</code>)</li><li>Sale updated (<code>SaleUpdated</code>)</li><li>Sale deleted (<code>SaleDeleted</code>)</li><li>Sale tag added (<code>SaleTagAdded</code>)</li><li>Sale tag removed (<code>SaleTagRemoved</code>)</li><li>Sale comment created (<code>SaleCommentCreated</code>)</li><li>Sale comment updated (<code>SaleCommentUpdated</code>)</li><li>Sale comment deleted (<code>SaleCommentDeleted</code>)</li><li>Sale file created (<code>SaleFileCreated</code>)</li><li>Sale file deleted (<code>SaleFileDeleted</code>)</li><li>Sale pipeline created (<code>SaleWorkflowCreated</code>)</li><li>Sale pipeline updated (<code>SaleWorkflowUpdated</code>)</li><li>Sale status created (<code>SaleStatusCreated</code>)</li><li>Sale status updated (<code>SaleStatusUpdated</code>)</li><li>Sale status deleted (<code>SaleStatusDeleted</code>)</li></ul> |
| **Calendar** | <ul><li>Calendar created (<code>CalendarCreated</code>)</li><li>Calendar updated (<code>CalendarUpdated</code>)</li><li>Calendar deleted (<code>CalendarDeleted</code>)</li></ul> |
| **Project** | <ul><li>Project created (<code>ProjectCreated</code>)</li><li>Project updated (<code>ProjectUpdated</code>)</li><li>Project deleted (<code>ProjectDeleted</code>)</li><li>Project task list created (<code>ProjectTaskListCreated</code>)</li><li>Project task list updated (<code>ProjectTaskListUpdated</code>)</li><li>Project task list deleted (<code>ProjectTaskListDeleted</code>)</li><li>Project task created (<code>ProjectTaskCreated</code>)</li><li>Project task updated (<code>ProjectTaskUpdated</code>)</li><li>Project task deleted (<code>ProjectTaskDeleted</code>)</li><li>Project task tag added (<code>ProjectTaskTagAdded</code>)</li><li>Project task tag removed (<code>ProjectTaskTagRemoved</code>)</li><li>Project task file created (<code>ProjectTaskFileCreated</code>)</li><li>Project task file deleted (<code>ProjectTaskFileDeleted</code>)</li><li>Project comment created (<code>ProjectCommentCreated</code>)</li><li>Project comment updated (<code>ProjectCommentUpdated</code>)</li><li>Project comment deleted (<code>ProjectCommentDeleted</code>)</li><li>Project time log created (<code>ProjectTimeLogCreated</code>)</li><li>Project time log updated (<code>ProjectTimeLogUpdated</code>)</li><li>Project time log deleted (<code>ProjectTimeLogDeleted</code>)</li><li>Project file created (<code>ProjectFileCreated</code>)</li><li>Project file deleted (<code>ProjectFileDeleted</code>)</li></ul> |
| **Communication** | <ul><li>SMS created (<code>SmsCreated</code>)</li><li>Phone call created (<code>PhoneCallCreated</code>)</li></ul> |
| **Marketing** | <ul><li>Form submission created (<code>FormSubmissionCreated</code>)</li><li>Landing page view created (<code>LandingPageViewCreated</code>)</li><li>Landing page link clicked (<code>LandingPageLinkClicked</code>)</li><li>Analytics custom event (<code>AnalyticsCustomEvent</code>)</li></ul> |
| **Finance** | <ul><li>Invoice created (<code>InvoiceCreated</code>)</li><li>Quotation created (<code>QuotationCreated</code>)</li></ul> |
| **Product & Service** | <ul><li>Service created (<code>ServiceCreated</code>)</li><li>Service updated (<code>ServiceUpdated</code>)</li><li>Service deleted (<code>ServiceDeleted</code>)</li><li>Service file created (<code>ServiceFileCreated</code>)</li><li>Service file deleted (<code>ServiceFileDeleted</code>)</li><li>Service tag added (<code>ServiceTagAdded</code>)</li><li>Service tag removed (<code>ServiceTagRemoved</code>)</li><li>Tax created (<code>TaxCreated</code>)</li><li>Tax deleted (<code>TaxDeleted</code>)</li><li>Product created (<code>ProductCreated</code>)</li><li>Product updated (<code>ProductUpdated</code>)</li><li>Product deleted (<code>ProductDeleted</code>)</li><li>Product tag added (<code>ProductTagAdded</code>)</li><li>Product tag removed (<code>ProductTagRemoved</code>)</li><li>Product file created (<code>ProductFileCreated</code>)</li><li>Product file deleted (<code>ProductFileDeleted</code>)</li></ul> |
| **Booking** | <ul><li>Booking created (<code>BookingCreated</code>)</li><li>Booking updated (<code>BookingUpdated</code>)</li><li>Booking deleted (<code>BookingDeleted</code>)</li></ul> |

Each event shows the name sent in `event` and `X-Webhook-Event` after it. A cancelled booking is sent
as `BookingUpdated`.

A website analytics custom event is sent for custom events recorded by the tracking snippet. Page
views are not sent.

### What is sent

Each event is sent as an HTTP POST with a JSON body:

```json
{
  "id": "an ID for this event",
  "event": "PersonCreated",
  "created_at": "2026-01-01T00:00:00Z",
  "data": { }
}
```

`data` holds the record in the same format as the API returns it. For a deleted record, `data` holds
only its `id`.

Each request has these headers:

| Header | What it holds |
|---|---|
| `Content-Type` | `application/json` |
| `X-Webhook-Event` | The event name, such as `PersonCreated` |
| `X-Webhook-Delivery` | A unique ID for this delivery |
| `X-Webhook-Signature` | The signature, as `sha256=` followed by the digest. Only sent when the webhook has a signing secret |

To check a signature, compute the HMAC-SHA256 of the raw request body using the signing secret as the
key, as lowercase hexadecimal, and compare it with the value after `sha256=`.

Events may not arrive in the order they happened, and the same event can arrive more than once. The
receiving system has to allow for both.

### Delivery and retries

A delivery succeeds when the receiving system replies with a 2xx status within 10 seconds. Anything
else is retried, up to 10 attempts in all. The waits between attempts are 10 seconds, 30 seconds,
2 minutes, 15 minutes, 30 minutes, 1 hour, 6 hours, 12 hours and 1 day. After the tenth attempt the
delivery is marked as failed.

A delivery is not sent if the webhook has been turned off or deleted by the time it is due.

### Delivery log

**Delivery Log** lists each event sent to the webhook:

| Column | What it shows |
|---|---|
| **Event** | The event |
| **Status** | **Pending**, **Delivered** or **Failed** |
| **Attempts** | How many attempts have been made, out of the maximum |
| **Response** | The HTTP status the receiving system replied with |
| **Last Attempt** | When it was last sent |
| **Created** | When the event happened |

**Retry now**, beside a delivery that has been tried and not delivered, sends it again straight
away.

## Related

- [Zapier](https://help.clockworkcrm.com/admin/zapier)
- [Connecting an AI assistant](https://help.clockworkcrm.com/general/ai-assistants)
- [Plugins](https://help.clockworkcrm.com/admin/plugins)