What Are Webhooks?
*If you need to switch API keys, please delete the old subscriptions first
Webhooks are notifications that are sent to a specified URL that describe a certain record related activity. The webhook notifies the receiving URL with a JSON response. Please note that webhooks can take up to 15 minutes.
Customers who integrate business systems want to be able to capture events that take place in Copper. These events within Copper can trigger events in other integrated systems.
When a record is created, changed or deleted in Copper, you can trigger a process in another system, after the initial change. For example, when a Person’s record is updated in Copper, the record for the same Person in a billing system is updated.
The event in Copper triggers the event in the connected system quickly, to minimize the chance of data inconsistency and to ensure that all required steps will be performed efficiently.
Concepts
Subscription: Register a URL that notifications will be sent to
Notification: The object delivered by a webhook
Topic: The type of event that triggers a notification and the object it is related to
Subscription Types
Definitions:
New = a new record is created
Update = any field in the existing entity record is changed. Excludes: new entity relationships, or any change in meta data.
Delete = an existing record is removed
What you can subscribe to:
| Event | ||
Type | New | Update | Delete |
Lead | yes | yes | yes |
Person | yes | yes | yes |
Company | yes | yes | yes |
Opportunity | yes | yes | yes |
Project | yes | yes | yes |
Task | yes | yes | yes |
Activity | yes | no | no |
User | no | no | no |
Account | no | no | no |
How to subscribe to a webhook
Method: POST
Event options: { “new”, “update”, “delete” }
Type options: { “lead”, “project”, “task”, “opportunity”, “company”, “person”, "activity_log"}
Optionally, you can include a custom secret in a key:value pair format
This data can be used to authenticate the request on the receiving endpoint
Target URL must be HTTPS
To test this you can use https://ngrok.com or http://requestb.in or Zapier
EXAMPLES OF SUBSCRIBING:
curl --request POST \
--header "Content-Type: application/json" \
--header "X-PW-AccessToken:YOURTOKEN" \
--header "X-PW-Application: developer_api" \
--header "X-PW-UserEmail:YOUREMAIL" \
https://api.prosperworks.com/developer_api/v1/webhooks \
--data '{"target":"https://yourTargetURL.com","type": "person","event": "update","secret":{"key":"value"}}'
curl -H "Content-Type: application/json" -X POST \
--header "X-PW-AccessToken:TOKEN" \
--header "X-PW-Application:developer_api" \
--header "X-PW-UserEmail:EMAIL" \
https://api.prosperworks.com/developer_api/v1/webhooks \
--data '{"target":"URL HERE", "type":"activity_log", "event": "new"}'
EXAMPLE RESPONSE:
{"id":12821,"target":"https://yourTargetURL.com","type":"person","event":"update","secret":{"key":"value"},"created_at":1481067722}
How to unsubscribe to a webhook
Method: DELETE
EXAMPLE OF UNSUBSCRIBING:
curl --request DELETE \
--header "Content-Type: application/json" \
--header "X-PW-AccessToken:TOKEN" \
--header "X-PW-Application: developer_api" \
--header "X-PW-UserEmail:EMAIL" \
https://api.prosperworks.com/developer_api/v1/webhooks/SUBSCRIPTION-ID
How you will receive notifications
Our server sends the notifications as POST requests.
Url: <provided by user>
Notifications deliver the id's of the involved records as an array. An array may contain a single e.g. [17] or multiple ids e.g. [17,287,542] but it will always be an array format.
How to see the status of a specific subscription
Method: GET
How to see what you have subscribed to
Method: GET
curl --request GET \
--header "Content-Type: application/json" \
--header "X-PW-AccessToken:TOKEN" \
--header "X-PW-Application: developer_api" \
--header "X-PW-UserEmail:EMAIL" \
https://api.prosperworks.com/developer_api/v1/webhooks
Rate limits
The number of notifications sent are bound by the following limits. When a rate limit is exhausted, our system will stop sending notifications until the rate limit renews
When a rate limit is exhausted, our system will stop sending notifications until the rate limit renews
600 notifications per minute per account
1,800 notifications per account for every 10 minutes
Retries
Our server currently sends the notifications once, regardless of the results of the request
Please make sure the endpoint you specify is available as needed to receive notifications