Skip to content

Receive notifications with webhooks

Webhooks send your systems a notification when something happens to a transaction, for example when a deposit completes or a withdrawal fails. You don't need to keep polling the API. Notifications go over HTTPS to an endpoint that you host.

Try it: interactive walkthrough

Click the highlighted area on each screen to move through the steps. All names, balances and addresses are demo data.

Choose the scope

At the top of Settings › Webhooks, choose:

  • All vaults, for webhooks at the enterprise level, or
  • a single vault, for webhooks that only cover that vault.

Verify that requests come from Hex Safe

The Webhook signing key on the same page is a public key. Each notification carries a signature, and your server should check it with this key before acting on the notification. The API documentation's webhooks page explains the payload and how to verify the signature.

Add a webhook

  1. In Settings › Webhooks, click Add Webhook.
  2. Keep Category set to Transaction.

  3. Choose the Transaction type:

    Type Covers
    withdrawal Assets leaving your vaults
    deposit Assets arriving in your vaults
    stake Staking
    unstake Unstaking
    sign-typed-data Typed-data signing requests

  4. Choose the Event that should trigger a notification, for example Completed or Failed. The events on offer depend on the transaction type.

  5. Enter your Webhook URL. It must be an HTTPS address that can be reached from the internet.
  6. Set Max retries and Retry interval (seconds). These control how often Hex Safe tries again if your endpoint doesn't accept a notification. The defaults are 5 retries, 60 seconds apart.
  7. Click Save.

Each webhook covers one transaction type and one event. To cover several, add one webhook for each combination.

Check deliveries

Delivery history, at the bottom of the page, lists recent delivery attempts for the scope you've selected. Check it first if your system isn't receiving notifications.