Subscriptions represent the various events that can be triggered within the system.
They are broken down into:
Top Level Subscriptions
ALL is the highest top level subscription and subscribes your webhook to all events triggered within the system.
| Subscription | Definition |
|---|
ALL | Subscribes to all other high level subscribtions defined within the system |
These other top level subscriptions, will subscribe to all events within its domain.
| Subscription | Definition | Domain |
|---|
ACCOUNT | Only events that deal with accounts | Accounts |
ASSET | Only events that deal with assets | Assets |
AUTH | Only events that deal with authentication | Authentications |
CUSTOMER | Only events that deal with customers | Customers |
INSTRUMENT | Only events that deal with instruments | Instruments |
INVESTMENT_TYPE | Only events that deal with investments | Investments |
PORTFOLIO | Only events that deal with portfolios | Portfolios |
REQUEST | Only events that deal with requests | Requests |
REPORT | Only events that deal with reports | Reports |
TRANSACTION | Only events that deal with transactions | Transactions |
WEBHOOK | Only events that deal with webhooks | Webhooks |
For example if you subcribed to ACCOUNT, it means that subscriptions to both
ACCOUNT.CREATED and ACCOUNT.UPDATED will be subcribed.
Low Level Subscriptions
These are more granular subscriptions that limits the event scope of your webhook configuration.
| Subscription | Definition | Domain |
|---|
ACCOUNT.CREATED | Triggered when an account is created | Accounts |
ACCOUNT.UPDATED | Triggered when an account is updated | Accounts |
ASSET.CREATED | Triggered when an asset is created | Assets |
ASSET.UPDATED | Triggered when an asset is updated | Assets |
AUTH.CREATED | Triggered when an auth token is created | Authentications |
AUTH.DELETED | Triggered when an auth token is deleted | Authentications |
CUSTOMER.CREATED | Triggered when a customer is created | Customers |
CUSTOMER.UPDATED | Triggered when a customer is updated | Customers |
INSTRUMENT.CREATED | Triggered when an instrument is created | Instruments |
INSTRUMENT.UPDATED | Triggered when an instrument is updated | Instruments |
INVESTMENT_TYPE.CREATED | Triggered when an investment is created | Investments |
INVESTMENT_TYPE.UPDATED | Triggered when an investment is updated | Investments |
PORTFOLIO.CREATED | Triggered when a portfolio is created | Portfolios |
PORTFOLIO.UPDATED | Triggered when a portfolio is updated | Portfolios |
REQUEST.CREATED | Triggered when a request is created | Requests |
REQUEST.UPDATED | Triggered when a request is updated | Requests |
WEBHOOK.CREATED | Triggered when a webhook is created. Subscription created automatically | Webhooks |
WEBHOOK.UPDATED | Triggered when a webhook is updated | Webhooks |
Combining Subscriptions
The flexible nature of this subscripton model means that they can be mixed and combined at your discretion.
This is especially important when using the ALL subscription.
| Combos | Definition |
|---|
| High Level + Low Level | Subscribe to all the events within the high level domain but only that low level event within its domain |
ALL + Low level | Subscribe to all events in the system but only that low level event with its domain |
ALL + High level | Same as subscribing to ALL |
| High Level | Only subscribes to all the events within the high level domain |
| Low Level | Only subscribes to the low level event within its domain |
Default Subscription
Upon creating a webhook, an automatic subscription to WEBHOOK.CREATED is made.
This will serves as an initial test of your webhook connection.
The payload should look similar to this:
{
"eventId": "38f429d1-2dda-4429-91e7-88696716c050",
"event": "WEBHOOK.CREATED",
"createdAt": 1732893584,
"data": {
"webhookId": 123456,
"status": "ACTIVE",
"url": "https://companyx.com/webhooks",
"subscriptions": [
...,
"WEBHOOK.CREATED"
],
"createdAt": 1732893594,
"updatedAt": 1732893594
}
}
Updating Subsubscriptons
Subscriptions can be updated by making a PUT request to /webhooks
curl --request PUT \
--url https://api.pipevest.com/v1/webhooks \
--header 'Authorization: Bearer 123456' \
--header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
--header 'Content-Type: application/application/json' \
--header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
--header 'Signature-Input: sig1=("Content-Type" "Content-Digest" "Content-Length" "Authorization" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
--header 'X-Client-Id: 123456' \
--header 'X-Idempotency-Key: 123456' \
...
--data '{"subscriptions": ["ALL"]}'
Updating the list of subscriptions will replace the previous subscriptions.
