Subscriptions

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.

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

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/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"]}'