Setting up Webhooks

This page will help you set up and start using webhooks to receive real-time notifications from Bitpanda Enterprise directly to your application. Follow these steps to configure your API URLs and begin leveraging the power of event-driven data delivery.

Step 1: Register your callback URL

Configure endpoint: Your application must have a publicly accessible endpoint to receive webhook notifications. This URL will be where we send JSON data when an event occurs.

Register URL & subscribe to events: Once available, pass this URL to our solution engineer together with the events that are relevant to your application.

There are two main options for differentiating between webhook calls:

URLs with different routes: You can set up a unique callback URL for each notification type, such as www.123.com/webhooks/webhook-1, webhook-2, etc. This approach allows you to process each event separately based on its endpoint, making it straightforward to distinguish between notification types.

Single URL with custom headers: Alternatively, if you prefer to use a single callback URL, we can configure custom headers for each notification type. This setup will enable you to identify the event type through the header, allowing flexible handling of different notifications within a single endpoint.

Each notification type also has a distinct payload structure, which aids in differentiation if using a single URL. Additionally, you have the option to activate notification types one at a time, providing control over your integration and easing testing.

Let us know which approach you would like to proceed with.

Step 2: Security Implementation

IP Filtering

Configure the Bitpanda Enterprise IPs to make sure the requests are correctly filtered.

Webhook Signature Verification

All webhook requests are signed using RFC 9421 HTTP Message Signatures with ECDSA P-256. You must verify these signatures before processing webhook data.

Required Headers

Every webhook includes these security headers:

Header	Purpose	Example
`Signature-Input`	Defines signed components and metadata	`sig1=("@method" "@target-uri" "host" "date" "content-digest" "content-type" "content-length" "x-BTS-idempotency-key");created=1640995200;expires=1640995500;keyid="key-id";alg="ecdsa-p256-sha256"`
`Signature`	Base64-encoded signature	`sig1=:MEUCIQDxHJKV3+...signature...:`
`Content-Digest`	SHA-256 hash of request body	`sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:`
`Date`	Request timestamp	`Mon, 22 Sep 2025 15:26:23 GMT`
`X-BTS-Idempotency-Key`	Unique event identifier	`BTS-a1b2c3d4e5f6...`

Step-by-Step Implementation

Step 1: Parse Signature Input

Extract signature metadata from the Signature-Input header:

Step 2: Fetch Public Key

Retrieve the signing key from our JWKS endpoint:

Step 3: Build Signature Base

Construct the string that was signed according to RFC 9421:

Step 4: Verify Signature

Validate the cryptographic signature:

Step 5: Validate Timestamps

Check signature freshness:

Step 6: Verify Content Digest

Validate request body integrity:

Complete Verification Function

Usage Example

Key Implementation Notes

Authentication: JWKS endpoint requires Authorization: Bearer YOUR_API_TOKEN

Components: Always signed in this exact order: @method, @target-uri, host, date, content-digest, content-type, content-length, x-BTS-idempotency-key

Base64 Encoding: Signatures use base64url encoding (may need conversion for your crypto library)

Timestamp Window: Signatures typically expire 5 minutes after creation

Host Header: Use the actual Host header value, not derived from URL

Target URI: Use the complete URL including scheme, host, and path

Contact your solution engineer to obtain your API token for JWKS access.

Step 3: Handle Incoming Data

Code and test your endpoint to accept POST requests. Ensure it can parse the JSON payload and handle different types of events according to your business logic as detailed in the following subsections. Note that you should process the events in an idempotent way as the events might be sent one or multiple times.

The X-BTS-Idempotency-Key header helps you handle duplicate deliveries:

Step 1: Register your callback URL#

Step 2: Security Implementation#

IP Filtering#

Webhook Signature Verification#

Required Headers#

Step-by-Step Implementation#

Step 1: Parse Signature Input#

Step 2: Fetch Public Key#

Step 3: Build Signature Base#

Step 4: Verify Signature#

Step 5: Validate Timestamps#

Step 6: Verify Content Digest#

Complete Verification Function#

Usage Example#

Key Implementation Notes#

Step 3: Handle Incoming Data#