Skip to main content

Webhook

Webhooks in the Cloud Wallet API allow applications to receive real-time event notifications related to wallet operations. By registering a webhook, you enable your system to automatically respond when key actions occur in a user's cloud wallet, without the need for continuous polling.

Endpoints​

The Cloud Wallet API provides the following webhook management endpoints:

Example: Registering a Webhook​

Follow these steps to configure a webhook for your Cloud Wallet:

  1. Visit the Hovi Cloud Wallet API Reference.

  2. Navigate to the Webhook section.

  3. To Register a webhook navigate to POST – Register Webhook endpoint.

  4. Click “Test Request” and provide the required inputs:

    • Enter your API key as a Bearer Token.
    • In the Request Body, specify your webhook URL (for example: https://your-app.com/webhook).

  5. Click “Send”. If successful, your webhook URL will be registered to receive Cloud Wallet event notifications.

Verify Webhook Signatures​

When you create a webhook, Hovi automatically generates a signing secret. Store this secret securely and use it to confirm that incoming webhook requests were sent by Hovi. Without signature verification, someone who knows your webhook URL could send fake event notifications to your application.

Every webhook request from Hovi includes the following headers:

HeaderDescription
x-webhook-timestampUnix timestamp in seconds when the request was created.
x-webhook-signatureHMAC-SHA256 signature beginning with sha256=.

Hovi generates the signature using your webhook secret, the timestamp, and the exact request body:

signedPayload = {timestamp}.{rawBody}
signature = sha256=HMAC-SHA256(webhookSecret, signedPayload)

To verify a webhook request:

  1. Read the timestamp and signature headers.
  2. Read and preserve the raw request body exactly as received, before any body parser processes it.
  3. Reject the request if either header or the body is missing.
  4. Reject timestamps outside your allowed window, such as five minutes.
  5. Calculate the expected signature using your webhook secret.
  6. Compare the calculated and received signatures using a timing-safe comparison.
  7. Process the event only when the signatures match. Otherwise, return 401 Unauthorized.

Important: Use the raw request body for verification. Parsing the JSON and serializing it again can change its formatting and cause a valid signature to be rejected.

Contents