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
URL: https://api.prosperworks.com/developer_api/v1/webhooks/<subscription_id>
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
URL: https://api.prosperworks.com/developer_api/v1/webhooks/<subscription_id>
How to see what you have subscribed to
Method: GET
URL: https://api.prosperworks.com/developer_api/v1/webhooks/
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
If you have any questions, please make a request here