Webhooks are event driven operations within the Pipevest system. Whenever an event is triggered a JSON payload is sent to all urls that have subscribed to the event. This document will guide you on how to create, update and get webhook details.

​
Creating an Auth Token

To create an Auth Token:

Make a POST request to /auth

  curl --request POST \
    --url https://api.pipevest.com/v1/auth\
    --header 'Authorization: Bearer 123456' \
    --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
    --header 'Content-Length: 18' \
    --header 'Content-Type: application/json' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "Content-Digest" "Content-Length" "Content-Type" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Idempotency-Key: 123456' \
    ...
    --data '{"url": "https://companyx.com/webhook2", "subscriptions": ["ALL"]}'

The resulting access token has a TTL of 60 mins.

​
Testing Webhook

To test a webhook:

Make a POST request to /auth/test

  curl --request POST \
    --url https://api.pipevest.com/v1/auth/test\
    --header 'Authorization: Bearer 123456' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Idempotency-Key: 123456' \
    ...

​
Updating Webhooks

If you need to change a webhook’s details:

Make a PUT request to /webhooks

  curl --request PUT \
    --url https://api.pipevest.com/v1/webhooks\
    ...
    --data '{"url": "https://companyx.com/webhook2", "subscriptions": ["ACCOUNT"]}'

Updaing the list of subscriptions will replace the previous subscriptions.

​
Retrieving Webhook Config

To retrieve a webhook’s configuration:

Make a GET request to /webhooks

  curl --request GET \
    --url https://api.pipevest.com/v1/webhooks\
    --header 'Authorization: Bearer 123456' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "X-Client-Id" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \

​
Retrieving Webhook Public Key

To retrieve a webhook’s public key:

Make a GET request to /webhooks/key

  curl --request GET \
    --url https://api.pipevest.com/v1/webhooks/key\
    --header 'Authorization: Bearer 123456' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "X-Client-Id" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \

This key is used to valdiate the webhook message.

​
Entity Reference

PropertyDefinition
webhookIdUnique webhook identifier
statusThe status of the webhook
urlA valid https url
subscriptionsList of webhook subscriptions
createdAtCreated at unix timestamp
updatedAtUpdated at unix timestamp

​
Status

NameDefinition
ACTIVEWebhook is currenting live
DEACTIVEDWebhook has been deactived

​
Webhook Subscriptions

SubscriptionDefinitionDomain
WEBHOOKOnly events that deal with webhooksWebhooks
WEBHOOK.CREATEDTriggered when a webhook is created. Subscription created automaticallyWebhooks
WEBHOOK.UPDATEDTriggered when a webhook is updatedWebhooks

Webhook Concepts

Deep dive into webhooks on the Pipevest platforms