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