Skip to main content

Webhooks

Hovi’s webhook endpoints allow tenants to configure webhooks to get notified whenever key events occur within your ecosystem. You can create, retrieve, and remove a webhook using Hovi’s webhook endpoints.

Hovi triggers webhooks for the following operations:

  1. Connection completion (Polygon, Indicio, Cheqd): Notifies when a connection has been successfully established.
  2. Credential acceptance (All ecosystems): Notifies when a user has accepted a credential.
  3. Proof verification (All ecosystems): Notifies when a proof verification process has been completed.

Endpoints​

The available webhook endpoints include:

  • Add Webhook: Allows a tenant to add a webhook URL.
  • Get All Webhooks​: Retrieves a list of all webhook or find a specific webhook by webhookId for a tenant.
  • Remove Webhooks: Allows a tenant to delete a webhook URL that is no longer needed.

Example: Configuring Webhooks in EU Digital Identity​

Follow these steps to configure a webhook in the EU Digital Identity ecosystem.

  1. Visit the Hovi API Reference.
  2. Select the EU Digital Identity Ecosystem API under the Business Wallet API dropdown.
  3. Navigate to Webhooks section.
  4. To create a webhook navigate to POST - Add Webhook endpoint and click “Test Request”.
  5. Enter the API key as a Bearer Token, provide the body parameters, and click “Send”.

A new webhook URL will be associated with your tenant.

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