API keys and webhooks
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.
Open in Clockwork CRMEnter your Clockwork CRM address at the top of the page to open this in your Clockwork CRM.
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
- Click Add API Key.
- Enter an API Key Name. Each key needs a different name.
- Optionally choose a User Scope (optional).
- Click Save.
- Open the key's actions menu and click Manage Permissions to choose what it can do. A new key has no permissions.
| 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 and 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 |
|
| Company |
|
| User |
|
| Resource |
|
| Case |
|
| Project |
|
| Automations |
|
| Email Accounts |
|
| Email Sending |
|
| Service |
|
| Tax |
|
| Sale |
|
| Telephony |
|
| Calendar |
|
| Knowledge Base |
|
| Marketing |
|
| Product |
|
| Webhooks |
|
| Tags |
|
| File Browser |
|
| Website Analytics |
|
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
- Click Add Webhook.
- Enter a Name and the Endpoint URL.
- Enter a Signing Secret, or click Generate to create one.
- Leave Active on. It is on for a new webhook.
- Under Events, tick the events to send.
- Click Save. It is not available until at least one event is ticked.
| 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 |
|
| Company |
|
| Case |
|
| Sale |
|
| Calendar |
|
| Project |
|
| Communication |
|
| Marketing |
|
| Finance |
|
| Product & Service |
|
| Booking |
|
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:
{
"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
Last updated