Overview

What are webhooks?

Webhooks are automated messages sent from Palisade to your back-end systems whenever specific events occur on the Palisade platform. The message, or payload, is sent to a unique URL on your server designed to receive webhook events.

Why are webhooks beneficial?

The automated nature of webhooks allows organizations to receive guaranteed, real-time updates about any interactions with their wallets (including creation of new wallets, deposits and withdrawals). This push-based approach eliminates the need for API/UI polling and ensures customers are immediately notified of important updates.

Webhook payload format

Webhook messages take the form of POST requests and are delivered as JSON objects with a base64-encoded payload. For example:

{
    "domain": "WALLET",
    "timestamp": "2025-05-08T14:15:37Z",
    "payload": "eyJpZCI6IjAxOTYxNTNiLTY3YmMtN2NkMy1iNTExLTM1NDM3M2QyODEzMCIsICJ2YXVsdElkIjoiMDE5NjE1MmQtNTI5NC03MzlkLTk5NDUtMmE0OTlmOWUzOTg5IiwgIm9yZ2FuaXphdGlvbklkIjoiMjFjODEzMTktNWI4My00NWY5LWI2NDgtNDIwNTUwODRhZjE1IiwgInF1b3J1bUlkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwgImNyZWF0ZWRCeSI6ImE1NWRmOWUwLWUxNGEtNDQxMC1hOTgzLTEyYWZhZTQ2NjYyZiIsICJjcmVhdGVkQXQiOiIyMDI1LTA0LTA4VDExOjQ4OjU2Ljg5OTA4NloiLCAidXBkYXRlZEF0IjoiMjAyNS0wNC0wOFQxMTo0ODo1Ni45MDA0OTBaIiwgIm5hbWUiOiJld3FmZXciLCAiZGVzY3JpcHRpb24iOiIiLCAiYWRkcmVzcyI6IjB4NDY0NDMyMGYzMUQ2OTU4RWQ4NjAzRWI2NjYwNDQ5NTBBYTY5NzAyZSIsICJwdWJsaWNLZXkiOiIwNDgxY2IwMmU4MjFlNTVhMmM2MTk2ZmZkZTM4MGJhM2I0OTgxN2JkYmYwMmYzMTVkYzI4YjU2ZjcwNzkyZDU2ZTZhZGFjOTE3ZTdhZGFmODdmMTBjMDg4NDA4YThjNmEwZTZkMTgwNzkzYzA1MGMzZDBjODc3MWNiOWRkZjgyNThkIiwgImtleXN0b3JlIjoiSFNNIiwgImJsb2NrY2hhaW4iOiJBUkJJVFJVTSIsICJzZXR0aW5ncyI6e30sICJzdGF0dXMiOiJQUk9WSVNJT05FRCJ9",
}

When decoded, the payload contains detailed information about the blockchain event. For example:

{
  "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 webhook contains a signature header you can use to verify that the payload is authentic. For example: MEQCIGjBwNKzzfqK9/Rb3Q2OQCyCuUiOOQz7vZwQ9iqInz76AiB/bvRn5iNUAkeVT80/pwhQ2LUajE6Mb2JtGt2mRmJMpg==

Retry Behaviour

The Palisade server expects an HTTP-200 (OK) response to confirm that a webhook notification has been successfully received. All webhook events must respond with this status to indicate successful processing.

If no response is received, Palisade will automatically retry the request several times based on the following schedule (in seconds): 0, 60, 120, 180, 320, 480, 840, 1500, 2820, 5400.

Retries will not be attempted for client-side errors (HTTP 4xx) except for the following cases:

429 - Too Many Requests: Indicates rate limits have been exceeded.
408 - Request Timeout: Indicates the server took too long to respond.

After a total of 10 failed attempts, the notification will be marked as failed and no further retries will be made.

Event Ordering

Although Palisade strives to send notifications in order (per resource), we cannot guarantee that events will always be delivered in the sequence they are generated. We recommend designing your endpoint to process events independently, without relying on their delivery order.