Before configuring a webhook there are a few reqiurements that must be met.

​
Requirements

1

Define Webook Url

  1. Webhook urls must be a valid HTTPS url
  2. The host of the url must be a DNS name and not an IP address

Example: https://companyx.com/webhooks

2

Determine Event Subscriptions

Decide which event subscriptions are appropriate for your use case.

Example: ACCOUNT, CUSTOMER.UPDATED, TRANSACTION

​
Configuration Request

Make a POST request to the /webhook to create and configure a webhook.

  curl --request POST \
    --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 '{"url": "https://companyx.com/webhooks", "subscriptions": ["ACCOUNT", "CUSTOMER.UPDATED", "TRANSACTION"]}'

​
Configuration Side Effects

Successfully, configuring a webhook will have the following additional results:

  1. Automatic subscription to WEBHOOK.CREATED Learn More

  2. Cryptographic public key generated. Learn More

​
Webhook Payload

The webhook payload is composed of the following:

NameDefinition
eventIdUnique event identifier. Should be used to deduplicate potentially duplicate events
eventThe event type. Example: ACCOUNT
createdAtUnix timestamp of when the event was created
dataThe data associated with the event

​
Example Payload

In the example below, an account was been created within the system.

{
  "eventId": "c00ec5f3-bbf7-4284-9e2f-88d886f5068c",
  "event": "ACCOUNT.CREATED",
  "createdAt": 1732893584,
  "data": {
    "accountId": 123456,
    "customerId": 123456,
    "status": "ACTIVE",
    "investmentType": "INTERNATIONAL_STOCKS",
    "currency": "ZMW",
    "createdAt": 1732893584,
    "updatedAt": 1732893584
  }
}