Webhook Streaming

Webhook is the default way to receive Event Streaming data. Blockdaemon delivers events by calling a URL you host.

When to use webhook

If you can host and expose an endpoint, a webhook is the simpler option. See WebSocket Streaming if you can't.

Setup flow

1. Register a webhook target

POST /targets
{
  "name": "my-webhook-target",
  "type": "webhook",
  "settings": {
    "destination": "https://example.com/webhook",
    "method": "POST",
    "secret": "a-long-random-secret-string"
  }
}

201 Created
{
  "id": "f86c1ef7-ea5e-49b9-b356-f83af7158ba5",
  "name": "my-webhook-target",
  "type": "webhook",
  "status": "active",
  "settings": {
    "destination": "https://example.com/webhook",
    "method": "POST",
    "secret": "************here"
  }
}

The target is created in the active state. It won't receive messages until it passes verification.

2. Complete verification (CRC)

Blockdaemon sends a GET request to your webhook with a challenge token:

GET https://example.com/webhook?token=3f9a1c7e

Your webhook computes an HMAC-SHA256 of the token using the target's secret, and returns it:

200 OK
{ "response_token": "sha256=6f2a9b3e1c8d..." }

Once verified, the target moves to connected. This check also runs periodically, every 10 minutes, for active and failed targets, not just at creation. See Webhook Verification Process for the full HMAC implementation.

3. (Optional) Create a template

Skip this step to use the default UNIFIED_V1 format. To use ALL_DATA or UNIFIED_V1_RAW instead, reference the template name directly when creating a rule in step 5, no separate template object is required for the built-in templates.

4. Create a variable

POST /variables
{ "name": "watch-address", "type": "string" }

201 Created
{ "id": "a3ec230e-b247-4ab1-9321-9e43cf6e8d5a", "name": "watch-address", "type": "string" }

POST /variables/a3ec230e-b247-4ab1-9321-9e43cf6e8d5a/values
{ "value": "0x3A024581D57D017453a67CF961771829B7F608F8" }

5. Create a rule

POST /rules
{
  "name": "watch-address-tx",
  "protocol": "ethereum",
  "network": "mainnet",
  "is_active": true,
  "condition_type": "match_var",
  "condition": [
    { "variable_type": "address", "variable_id": "a3ec230e-b247-4ab1-9321-9e43cf6e8d5a" }
  ],
  "target": "f86c1ef7-ea5e-49b9-b356-f83af7158ba5",
  "template": "UNIFIED_V1"
}

Once the rule is active, matching events start arriving at the target's destination as UNIFIED_V1 messages. See Webhook Handling for retry, backoff, and reconnection behavior.

There is no heartbeat or keepalive for webhook targets. Health is inferred from target status transitions, the periodic CRC check, and delivery response codes — a non-2xx response triggers the retry cycle described in Webhook Handling.

Successful delivery

sequenceDiagram
    actor Customer
    participant ES as Access Event Streaming
    participant Indexer as Access Blockchain Indexing Stack
    participant HA as HA Node Cluster

    Customer->>ES: Create Target
    Customer->>ES: [POST] Create Target
    ES->>ES: Target Status Active
    ES->>Customer: [GET] Valid User Webhook
    Customer->>ES: CRC response
    ES->>ES: Target Status Connected
    Customer->>ES: Create Template
    Customer->>ES: Create Rule
    ES->>Indexer: Apply Rule

    loop
        HA->>Indexer: Consume Blockchain Data
        Indexer->>ES: Adds Messages to Target Topic
    end

    loop
        ES->>ES: Read Messages For User
        ES->>ES: Apply Template
        ES->>Customer: Send formatted message to Target
    end

Delivery failure and recovery

After 10 consecutive failed delivery attempts, the target moves to failed and stops receiving messages until it passes verification again — see Webhook Handling for the retry/backoff mechanics this diagram summarizes.

sequenceDiagram
    actor Customer
    participant ES as Access Event Streaming
    participant Indexer as Access Blockchain Indexing Stack
    participant HA as HA Node Cluster

    Customer->>ES: Create Target
    Customer->>ES: [POST] Create Target
    ES->>ES: Target Status Active
    ES->>Customer: [GET] Valid User Webhook
    Customer->>ES: CRC response
    ES->>ES: Target Status Connected
    Customer->>ES: Create Template
    participant ES as Access Event Streaming
    participant Indexer as Access Blockchain Indexing Stack
    participant HA as HA Node Cluster

    Customer->>ES: Create Rule
    ES->>Indexer: Apply Rule

    loop
        HA->>Indexer: Consume Blockchain Data
        Indexer->>ES: Adds Messages to Target Topic
    end

    alt 10 failed attempts
        ES->>ES: Read Messages For User
        ES->>ES: Apply Template
        ES->>Customer: Send formatted message to Target
        Customer-->>ES: 502 Bad Gateway
    end

    ES->>ES: Target Status Failed
    ES->>Customer: [GET] Valid User Webhook
    Customer-->>ES: CRC response
    ES->>ES: Target Status Connected

    loop
        ES->>ES: Read Messages For User
        ES->>ES: Apply Template
        ES->>Customer: Send formatted message to Target
    end

Security

HMAC-SHA256 message signing

Every message includes an x-bd-webhooks-signature header, an HMAC-SHA256 signature over the request body using your target's webhook secret. This is the primary authentication mechanism for webhook messages. See Validate Message Origin for reference code.

Source IP allow-listing

Blockdaemon delivers webhook messages from a fixed set of source IPs, so you can allow-list inbound traffic to your webhook endpoint:

• 35.245.225.131
• 34.150.141.91
• 34.85.141.205