Guides
SupportStatus
Start typing to search…

Step 2. Create a New Target

Learn how to configure targets for event streaming.

❗️

Note

Each call incurs a fixed CU charge, plus additional CUs for API operations. See the Compute Units Usage page for details.

Create a Target

Now you need to set up a webhook target to start receiving events. A target will serve as a destination in a rule that provides you with the data you desire. You can do this by using the Target endpoint.

Request Payload

curl --request POST \
     --url https://svc.blockdaemon.com/streaming/v2/targets \
     --header 'X-API-Key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "string",
  "description": "string",
  "type": "webhook",
  "settings": {
    "destination": "string",
    "method": "POST",
    "secret": "string"
  },
  "max_buffer_count": 10000
}
'

The request body includes the following parameters:

FieldsRequired/OptionalDetails
nameRequiredThe name of your target. Each resource should have a unique name.
descriptionOptionalA description of your target.
typeRequiredThe type of target which currently limited to webhook.
settingsRequiredThe configuration of a webhook target.
destinationRequiredThe destination URL where we can reach this webhook.
methodRequiredThe HTTP method for the webhook (in this case, POST).
secretRequiredA private webhook secret with a minimum string length of 10 characters. This is used as the challenge token for webhook verification process.
max_buffer_countOptionalMaximum number of items allowed in the webhook target's buffer.

Response Payload

Below is the successful response.

{
    "created_at": "2024-03-06T09:48:06.673414Z",
    "current_buffer_count": 0,
    "description": "Documentation webhook target",
    "id": "8918a2f1-28d6-4e2f-837b-fb49ec09daaf",
    "max_buffer_count": 100,
    "name": "docs webhook target example",
    "settings": {
        "destination": "http://example.com/webhook",
        "method": "POST",
        "secret": "************here"
    },
    "status": "active",
    "type": "webhook",
    "updated_at": "2024-03-06T09:48:06.673414Z"
}

It includes the following details:

FieldsDetails
idUnique identifier for your webhook target, necessary for creating rules. You will need this ID to create a rule.
created_at & updated_atA timestamp for when the target was created and last updated.
max_buffer_countMaximum number of events that will buffer for your target. If your target is slow or temporarily offline, event streaming will buffer messages up to this limit.
destinationURL to send webhook payloads for processing or notification.
statusStatus of your webhook. It must be "connected" before receiving events. Refer to the Webhook Target Reference.
👍

Note:

You can use one webhook target for multiple rules by using its id.


Managing Target

Verify Target

Validate a target to check if it can receive a message. This endpoint is also useful for debugging issues during the webhook verification process.

Example Payload

Make sure the target has a valid secret configured, as this is used to generate the validation token.

curl -X POST "https://svc.Blockdaemon.com/streaming/v2/targets/{TARGET ID HERE}/validate-verification" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
  "status": "success",
  "error_status_code": 0,
  "error_response_message": "string",
  "duration": "string"
}

Failure Example

An incorrect or misformatted secret can cause validation to fail. For example, avoid using spaces in the secret — use hyphens (-) instead.

{
    "duration": "4.165116ms",
    "error_response_message": "failed validation token is not as expected",
    "error_status_code": 200,
    "status": "failed"
}

To resolve this, you must update the target with a valid secret, then retry.

Update Target

Update a target by its ID. You can modify the destination, secret, name, and other target settings. To partially update a target, see: Partially Update a Target

Example Payload

curl --request PUT \
     --url https://svc.blockdaemon.com/streaming/v2/targets/{TARGET ID HERE} \
     --header 'X-API-Key: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "documentation target",
  "description": "documentation target",
  "type": "webhook",
  "settings": {
    "destination": "string",
    "method": "POST",
    "secret": "string"
  },
  "max_buffer_count": 10000
}
'
{
    "created_at": "2024-02-05T12:36:38.113436Z",
    "current_buffer_count": 0,
    "description": "documentation webhook target",
    "id": "<TARGET_ID>",
    "max_buffer_count": 100,
    "name": "documentation target",
    "settings": {
        "destination": "www.blockdaemon.com/webhook/doctarget",
        "method": "POST",
        "secret": "************cret"
    },
    "status": "active",
    "type": "webhook",
    "updated_at": "2024-02-05T12:46:35.169515Z"
}

Get Target Details

Retrieve the full configuration of a specific target by its ID. Use this to review webhook settings, buffer usage, and metadata.

Example Payload

curl --request GET \
     --url https://svc.blockdaemon.com/streaming/v2/targets/{TARGET ID HERE} \
     --header 'X-API-Key: YOUR_API_KEY' \
     --header 'accept: application/json'
{
    "created_at": "2024-02-05T12:36:38.113436Z",
    "current_buffer_count": 0,
    "description": "documentation webhook target",
    "id": "<TARGET_ID>",
    "max_buffer_count": 100,
    "name": "documentation target",
    "settings": {
        "destination": "www.blockdaemon.com/webhook/doctarget",
        "method": "POST",
        "secret": "************cret"
    },
    "status": "active",
    "type": "webhook",
    "updated_at": "2024-02-05T12:46:35.169515Z"
}

Delete Target

Delete a target by its ID. This action cannot be undone.

Example Payload

curl --request DELETE \
     --url https://svc.blockdaemon.com/streaming/v2/targets/{TARGET ID HERE} \
     --header 'X-API-Key: YOUR_API_KEY' \
     --header 'accept: application/json'
A 204 response status indicates the target was successfully deleted.

Target Validate Message

Simulate message delivery to a target after verification. This allows you to test if a target webhook receives and processes event messages correctly.

Example Payload

This requires a predefined template. Please refer to this page for creating a template. It will send a sample message to your target based on the protocol and type.

curl --request POST \
     --url https://svc.blockdaemon.com/streaming/v2/targets/{TARGET ID HERE}/validate-message \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "protocol": "string",
  "type": "string",
  "template": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'
{
    "duration": "374.944099ms",
    "status": "success"
}

Following a successful call, the webhook will receive a sample message useful for tracking and verifying transactions on the blockchain. See the sample below.

{
  "accessList": [],
  "additionalFields": {
    "yParity": "0x0"
  },
  "bd_metadata": {
    "network": "mainnet",
    "protocol": "ethereum",
    "schema": "Transaction",
    "version": 0
  },
  "blockHash": "0xa101fa10de106b17bafb85b4fab089af7156ef7bb71e12701711f392176efc25",
  "blockNumber": "0x1227602",
  "chainId": {
    "string": "0x1"
  },
  "contractAddress": null,
  "creates": null,
  "cumulativeGasUsed": {
    "string": "0x2eed3f"
  },
  "effectiveGasPrice": {
    "string": "0x959dc078d"
  },
  "from": "0x28C6c06298d514Db089934071355E5743bf21d60",
  "gas": "0x35d14",
  "gasPrice": "0x959dc078d",
  "gasUsed": {
    "string": "0xb429"
  },
  "hash": "0x66cd831693896d069773b1b4fb0b170eb3265f8a5ba7852c6185695d241fa98e",
  "input": {
    "string": "0xa9059cbb000000000000000000000000476a3d7bae70f59cfa8db1d8fe795f285cadfc6700000000000000000000000000000000000000000000000000000001f6210c7d"
  },
  "logsBloom": {
    "string": "0x00000000000000000000080000000004000000000000000000000000000000000000000000000000000001000000010000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000200000000002000010000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000080000000000000000000000000000000020000000000000002000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
  },
  "maxFeePerGas": {
    "string": "0x17bfac7c00"
  },
  "maxPriorityFeePerGas": {
    "string": "0x77359400"
  },
  "nonce": "0x85b19b",
  "publicKey": null,
  "r": "0x268b6c7f957544c9723ac118c3270e388889f25e3eac24fa71076ae7f35f2d1a",
  "raw": null,
  "root": null,
  "s": "0x79993142d0fcaeac62d757832e284b57b147554ac8c808c30e7914fe66bd385d",
  "status": {
    "string": "0x1"
  },
  "timestamp": {
    "long": 1705603907
  },
  "to": {
    "string": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
  },
  "transactionIndex": "0x2d",
  "type": {
    "string": "0x2"
  },
  "uuid": {
    "string": "e65bfb70-31e8-4465-b528-9de9beb4845f"
  },
  "v": "0x0",
  "value": {
    "string": "0x0"
  }
}

👋 Need Help?

Contact us through email or our support page for any issues, bugs, or assistance you may need.

Updated 26 days ago