Subscriptions represent the various events that can be triggered within the system. They are broken down into:

  • Top-level
  • Low-level

​
Top Level Subscriptions

ALL is the highest top level subscription and subscribes your webhook to all events triggered within the system.

SubscriptionDefinition
ALLSubscribes to all other high level subscribtions defined within the system

These other top level subscriptions, will subscribe to all events within its domain.

SubscriptionDefinitionDomain
ACCOUNTOnly events that deal with accountsAccounts
ASSETOnly events that deal with assetsAssets
AUTHOnly events that deal with authenticationAuthentications
CUSTOMEROnly events that deal with customersCustomers
INSTRUMENTOnly events that deal with instrumentsInstruments
INVESTMENT_TYPEOnly events that deal with investmentsInvestments
PORTFOLIOOnly events that deal with portfoliosPortfolios
REQUESTOnly events that deal with requestsRequests
REPORTOnly events that deal with reportsReports
TRANSACTIONOnly events that deal with transactionsTransactions
WEBHOOKOnly events that deal with webhooksWebhooks

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.

SubscriptionDefinitionDomain
ACCOUNT.CREATEDTriggered when an account is createdAccounts
ACCOUNT.UPDATEDTriggered when an account is updatedAccounts
ASSET.CREATEDTriggered when an asset is createdAssets
ASSET.UPDATEDTriggered when an asset is updatedAssets
AUTH.CREATEDTriggered when an auth token is createdAuthentications
AUTH.DELETEDTriggered when an auth token is deletedAuthentications
CUSTOMER.CREATEDTriggered when a customer is createdCustomers
CUSTOMER.UPDATEDTriggered when a customer is updatedCustomers
INSTRUMENT.CREATEDTriggered when an instrument is createdInstruments
INSTRUMENT.UPDATEDTriggered when an instrument is updatedInstruments
INVESTMENT_TYPE.CREATEDTriggered when an investment is createdInvestments
INVESTMENT_TYPE.UPDATEDTriggered when an investment is updatedInvestments
PORTFOLIO.CREATEDTriggered when a portfolio is createdPortfolios
PORTFOLIO.UPDATEDTriggered when a portfolio is updatedPortfolios
REQUEST.CREATEDTriggered when a request is createdRequests
REQUEST.UPDATEDTriggered when a request is updatedRequests
WEBHOOK.CREATEDTriggered when a webhook is created. Subscription created automaticallyWebhooks
WEBHOOK.UPDATEDTriggered when a webhook is updatedWebhooks

​
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.

CombosDefinition
High Level + Low LevelSubscribe to all the events within the high level domain but only that low level event within its domain
ALL + Low levelSubscribe to all events in the system but only that low level event with its domain
ALL + High levelSame as subscribing to ALL
High LevelOnly subscribes to all the events within the high level domain
Low LevelOnly 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.