Webhooks

Mostly planned — one endpoint is live. Creating, updating, retrieving and testing webhooks is not yet enabled to call, and no events are delivered; those sections are documented so you can design your integration ahead of time. The exception is retrieving the webhook public key, which is live today. For initial go-live, investment flows transact via USSD. If webhooks are part of your integration plan, contact us. See what’s available today.

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 a Webhook

To create a webhook:

Tip

Make a POST request to /webhooks

  curl --request POST \
    --url https://api.pipevest.com/v1/webhooks\
    --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"]}'

Note

The resulting access token has a TTL of 60 mins.

Testing Webhook

To test a webhook:

Tip

Make a POST request to /webhooks/test

  curl --request POST \
    --url https://api.pipevest.com/v1/webhooks/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:

Tip

Make a PUT request to /webhooks

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

Caution

Updaing the list of subscriptions will replace the previous subscriptions.

Retrieving Webhook Config

To retrieve a webhook’s configuration:

Tip

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 the Webhook Public Key

Live today. To retrieve the public key Pipevest signs webhooks with:

Tip

Make a GET request to /v1/webhooks/key

Public keys are non-secret, so this endpoint is unauthenticated — send no bearer token, no X-Client-Id and no signature of your own.

  curl --request GET \
    --url https://api.pipevest.com/v1/webhooks/key

Note

There is one server-wide signing key per environment, not one per webhook. The response carries it as both an SPKI PEM and a JWKS; use it to validate the webhook message.

The response reports the key’s id as keyId, and as the JWKS kid — pipevest-live-ed25519-2 in production and pipevest-staging-ed25519-2 in the sandbox. A key id names exactly one key: the environment and the key generation are both part of it, so the two environments never collide and a rotation always changes the key id. Cache the key against the environment’s base url and its key id, and re-fetch this endpoint whenever a webhook arrives bearing a key id you do not hold. Key ids and their handling are covered in full under webhook validation.

Entity Reference

Property	Definition
webhookId	Unique webhook identifier
status	The status of the webhook
url	A valid https url
subscriptions	List of webhook subscriptions
createdAt	Created at unix timestamp
updatedAt	Updated at unix timestamp

Status

Name	Definition
ACTIVE	Webhook is currenting live
DEACTIVED	Webhook has been deactived

Webhook Subscriptions

Subscription	Definition	Domain
WEBHOOK	Only events that deal with webhooks	Webhooks
WEBHOOK.CREATED	Triggered when a webhook is created. Subscription created automatically	Webhooks
WEBHOOK.UPDATED	Triggered when a webhook is updated	Webhooks

Webhook Concepts

Deep dive into webhooks on the Pipevest platforms