Learn more about Copper Webhooks

Learn more about Copper Webhooks

Success at Copper avatar
Written by Success at Copper
Updated over a week ago

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

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:

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

Did this answer your question?