Skip to content

Webhook Support Now Available

Today, we are excited to announce the release of Webhook Support in Wallet-as-a-Service (Palisade), enabling you to receive real-time updates about transactions and wallet events directly to your systems.

This new feature empowers you to build more responsive applications that can react instantly to blockchain events managed through the Wallet-as-a-Service (Palisade) platform.

Only owners and administrators can configure webhooks.

Why

Real-time notifications are essential for businesses that need to monitor blockchain transactions and wallet updates without constant API polling. Until now, customers had to periodically check for updates via our API, which is inefficient and can lead to delays in detecting critical events.

What are Webhooks?

Webhooks allow Wallet-as-a-Service (Palisade) to send POST requests to your backend systems whenever specific events occur on our platform. This push-based approach eliminates the need for polling and ensures you're immediately notified of important updates.

Key Features

  • Comprehensive Event Coverage: Receive notifications for all transaction and wallet events across your organization.
  • Guaranteed Delivery: At-least-once delivery ensures you never miss critical updates.
  • Secure Communication: All webhook messages are cryptographically signed with our private key, allowing you to verify authenticity.
  • Flexible Configuration: Set up and manage webhooks through the Wallet-as-a-Service (Palisade) Console UI or via our API.

Webhook Payload Format

Webhook payloads are delivered as JSON objects with a base64-encoded payload:

{
    "domain": "WALLET",
    "payload": "eyJpZCI6IjAxOTYxNTNiLTY3YmMtN2NkMy1iNTExLTM1NDM3M2QyODEzMCIsICJ2YXVsdElkIjoiMDE5NjE1MmQtNTI5NC03MzlkLTk5NDUtMmE0OTlmOWUzOTg5IiwgIm9yZ2FuaXphdGlvbklkIjoiMjFjODEzMTktNWI4My00NWY5LWI2NDgtNDIwNTUwODRhZjE1IiwgInF1b3J1bUlkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwgImNyZWF0ZWRCeSI6ImE1NWRmOWUwLWUxNGEtNDQxMC1hOTgzLTEyYWZhZTQ2NjYyZiIsICJjcmVhdGVkQXQiOiIyMDI1LTA0LTA4VDExOjQ4OjU2Ljg5OTA4NloiLCAidXBkYXRlZEF0IjoiMjAyNS0wNC0wOFQxMTo0ODo1Ni45MDA0OTBaIiwgIm5hbWUiOiJld3FmZXciLCAiZGVzY3JpcHRpb24iOiIiLCAiYWRkcmVzcyI6IjB4NDY0NDMyMGYzMUQ2OTU4RWQ4NjAzRWI2NjYwNDQ5NTBBYTY5NzAyZSIsICJwdWJsaWNLZXkiOiIwNDgxY2IwMmU4MjFlNTVhMmM2MTk2ZmZkZTM4MGJhM2I0OTgxN2JkYmYwMmYzMTVkYzI4YjU2ZjcwNzkyZDU2ZTZhZGFjOTE3ZTdhZGFmODdmMTBjMDg4NDA4YThjNmEwZTZkMTgwNzkzYzA1MGMzZDBjODc3MWNiOWRkZjgyNThkIiwgImtleXN0b3JlIjoiSFNNIiwgImJsb2NrY2hhaW4iOiJBUkJJVFJVTSIsICJzZXR0aW5ncyI6e30sICJzdGF0dXMiOiJQUk9WSVNJT05FRCJ9",
}

When decoded, the payload contains detailed information about the event:

{
  "id": "0196153b-67bc-7cd3-b511-354373d28130",
  "vaultId": "0196152d-5294-739d-9945-2a499f9e3989",
  "organizationId": "21c81319-5b83-45f9-b648-42055084af15",
  "createdBy": "a55df9e0-e14a-4410-a983-12afae46662f",
  "createdAt": "2025-04-08T11:48:56.899086Z",
  "updatedAt": "2025-04-08T11:48:56.900490Z",
  "name": "My Wallet",
  "address": "0x4644320f31D6958Ed8603Eb666044950Aa69702e",
  "publicKey": "0481cb02e821e55a2c6196ffde380ba3b49817bdbf02f315dc28b56f70792d56e6adac917e7adaf87f10c088408a8c6a0e6d180793c050c3d0c8771cb9ddf8258d",
  "keystore": "HSM",
  "blockchain": "ARBITRUM",
  "settings": {},
  "status": "PROVISIONED"
}

The request contains a signature header you can use to verify that the payload is authentic, for example MEQCIGjBwNKzzfqK9/Rb3Q2OQCyCuUiOOQz7vZwQ9iqInz76AiB/bvRn5iNUAkeVT80/pwhQ2LUajE6Mb2JtGt2mRmJMpg==

How to Get Started

  1. Create a Webhook Endpoint: Develop a HTTPS endpoint on your server to receive webhook events.
  2. Register Your Webhook: Configure your webhook URL through the Wallet-as-a-Service (Palisade) Console or API.
  3. Implement Verification: Use our signature to verify that incoming webhook requests are authentic.
  4. Process Events: Handle the webhook payload data in your application logic.

Signature Verification

When you create a webhook, Wallet-as-a-Service (Palisade) generates and returns a P-256 ECDSA public key in ASN.1 DER format:

{
  "id": "a6a1e8bd-30eb-419f-b6ba-e7ac11e86f84",
  "name": "wefewfwe",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEpHiEkdd/ba5dU4sNCgsWrMOE6fLakHywl0OgF5aVfxkiqNh22oybRAREev7jvnwH4jqitHx79KGi6CMwiJjmaw==",
  // other fields omitted
}

To verify the authenticity of webhook deliveries, follow these general steps:

  1. Store the Public Key: Save the publicKey when you create your webhook.
  2. Extract the Signature: Get the signature from the webhook event headers (it's in ASN.1 DER format, base64-encoded).
  3. Hash the Payload: Create a SHA-256 hash of the base64-encoded payload.
  4. Verify the Signature: Use the public key to verify that the signature matches the payload hash.

Most programming languages have cryptography libraries that support ECDSA verification.

API Endpoints

Manage your webhooks programmatically with our comprehensive API, more information can be found in the Wallet-as-a-Service (Palisade) API.

Security Requirements & Best Practices

  • HTTPS Only: All webhook endpoints must use HTTPS for secure communication.
  • Signature Verification: Always verify the webhook signature to ensure authenticity (see details below).
  • Response Codes: Return a 200 OK response code to acknowledge receipt of the webhook.
  • Idempotency: Implement idempotent processing to handle potential duplicate deliveries.

Delivery Behavior

Currently, webhooks follow a fire and forget model where Wallet-as-a-Service (Palisade) attempts to deliver each message to the webhook once. In the future, we may implement a retry mechanism for messages where the endpoint does not respond with a 200 OK code, please let us know if this feature would be useful to you.