Skip to content
Prividium

Webhooks Overview

A webhook is an HTTPS callback that sends your service real-time notifications about on-chain activity. When monitored events or addresses match your subscription, a signed HTTP request is delivered to your configured endpoint.

The Webhook service intends to be Open Webhook Standards Complaint:

Standard Webhooks references:

Supported Webhook Types

Prividium supports two webhook resource types:

Event Webhooks

One endpoint subscribed to a single contract event.

  • contract (required)
  • topic0 (required)
  • from_block (optional)

Each event webhook represents one contract event subscription.

Address Webhooks

One endpoint subscribed to one or more addresses.

  • addresses (one or more required)
  • from_block (optional)

Each address webhook represents one address subscription group.

Note: Internal transaction monitoring is not currently supported.

Authentication

All webhook management routes require authentication.

Ensure your requests include valid credentials when interacting with the API.

Signing Keys

Each webhook is associated with a signing key used to verify delivery authenticity.

  • The signing key is returned only once at creation time.
  • Store it securely.
  • If lost, you must rotate the key.

The term signing key may also appear as signing secret in some contexts. They refer to the same value.

Signature Verification Requirements

When verifying webhook deliveries:

  • Always verify using the raw request body
  • Do not re-serialize JSON before verification

Re-serialization will invalidate the signature and cause verification failures.

Table of Contents

  1. Using Webhooks in the UI
  2. Event Webhooks API
  3. Address Webhooks API
  4. Webhook Delivery Handling
  5. Verifying Signatures
  6. Rotating Signing Keys

Quick Start

  1. Obtain an auth token (see Manage Auth Tokens Programmatically).
  2. Create an event or address webhook using the UI or authenticated API.
  3. Store the signing key immediately when it is shown.
  4. Verify each delivery signature before processing payloads.
  5. If rotating keys, accept signatures from all active keys during the overlap window.

Local Development Notes

  • API examples in this section use permissions-api at http://localhost:8000/api/v1.

  • Receiver endpoint examples use a publicly accessible HTTPS URL (for example, an ngrok forwarding URL).

    Example: https://3c4a-142-160-238-84.ngrok-free.app/webhook

When developing locally, expose your mock receiver with ngrok and use the generated HTTPS forwarding URL as your webhook endpoint.