Webhooks¶
Webhooks allow systems integrated with Copper to receive near real-time notification of certain events so that data updates and workflows can be triggered.
Webhook concepts¶
| Concept | Description |
|---|---|
| Subscription | Register a URL that notifications will be sent to when a specific event type occurs. |
| Event | A specific action in Copper that triggers a notification. |
| Notification | The object delivered by an https request (webhook) to the specified URL. |
Event Types¶
The following events are available for subscription:
| Type | Description |
|---|---|
| Create | A new record is created. |
| Update | Any field in the existing entity record is changed. Excludes: new entity relationships, new Activity or any change in meta data. |
| Delete | An existing record is removed. |
Entity types¶
Events are available for the different entity types as follows.
| Record Type | Create | Update | Delete | Type |
|---|---|---|---|---|
| Lead | yes | yes | yes | "lead" |
| Person | yes | yes | yes | "person" |
| Company | yes | yes | yes | "company" |
| Opportunity | yes | yes | yes | "opportunity" |
| Project | yes | yes | yes | "project" |
| Task | yes | yes | yes | "task" |
| Activity | yes | yes | yes | "activity_log" |
Technical considerations¶
Subscription count¶
You may have up to 100 active subscriptions per account.
Rate limits¶
The number of notifications sent are bound by the following limits:
- 600 notifications per minute per account
- 1,800 notifications per account for every 10 minutes
Multi-event notifications¶
Our notifications always send an array with the IDs of the records involved. The array contains at least 1 ID and may contain up to 30 ID's in a single notification. If more than 30 records are affected then we send multiple notifications, each with up to 30 IDs. Each notification counts as a single request towards the rate limit, regardless of the number of IDs it contains.
Retries¶
Our notifications are fired at most once per event, and we do not retry them, regardless of the status returned by the notification endpoint.
HTTPS only¶
For security reasons only https:// endpoints are accepted for the notification URL.
Webhook properties¶
| Field | Type | Details |
|---|---|---|
| id | identifier | The unique ID of the subscription |
| target | string | The URL where the notification will be sent |
| type | string | The entity type on which the event occurs |
| event | string | The type of event that triggers the notification new, update, delete |
| secret | object | (Optional) Arbitrary data (e.g. for authentication) to pass to the webhook event, in the form { "key1": "value1", "key2": "value2", ... } |
| headers | object | (Optional) HTTP headers to pass to the webhook, in the form { "key1": "value1", "key2": "value2", ... } |
| custom_field_computed_values | boolean | If set to true, dropdown custom fields (standard and multi-select) will have their option_ids converted to the option names. |
| created_at | number | The date when the subscription was created |