Webhook - Goldsky Docs

Overview

Send data to HTTP endpoints as JSON payloads over HTTP POST. The sink guarantees at-least-once delivery and retries transient failures with exponential backoff, so your endpoint only needs to return a 2xx status code to acknowledge the batch.

Configuration

sinks:
  my_webhook_sink:
    type: webhook
    from: my_transform
    url: https://api.example.com/endpoint
    secret_name: MY_WEBHOOK_SECRET
    one_row_per_request: true # or false (default)
    headers:
      X-Custom-Header: my-value

Parameters

string

required

Must be webhook.

string

required

Name of the transform or source to read data from.

string

required

Fully-qualified HTTP(S) endpoint URL to send data to (for example, https://api.example.com/endpoint). The sink sends POST requests to this URL.

string

Name of a Goldsky httpauth secret. Both the header name and value stored in the secret are injected into every outgoing request. See Secret creation below.

boolean

default:"false"

If true, each row is sent as its own request with a single JSON object body. If false (default), rows are batched and sent as a JSON array body.

object

Additional HTTP headers to include with each request. Content-Type: application/json is set automatically if you don’t specify one. You cannot set the same header here that secret_name provides — pick one or the other.

string

Column that uniquely identifies each row. Used for checkpointing and side-output tracking. Inherited from the upstream source or transform when omitted.

integer

default:"1000"

Runtime-level parameter — maximum number of rows the Turbo runtime buffers before flushing a batch. When one_row_per_request: false, this is also the maximum number of rows included in a single JSON-array request. See Batching on the overview page.

string

default:"1s"

Runtime-level parameter — maximum time the Turbo runtime waits before flushing a batch, even if batch_size has not been reached. Accepts humantime durations such as 500ms, 1s, or 30s. See Batching.

Request Format

Each request is an HTTP POST with Content-Type: application/json. Single row (one_row_per_request: true):

{
  "id": "abc123",
  "address": "0x...",
  "value": "1000000",
  "timestamp": "2024-01-01T00:00:00Z"
}

Batch (one_row_per_request: false):

[
  {
    "id": "abc123",
    "address": "0x...",
    "value": "1000000"
  },
  {
    "id": "def456",
    "address": "0x...",
    "value": "2000000"
  }
]

Secret creation

To securely authenticate with your webhook endpoint, create an httpauth secret using the Goldsky CLI:

goldsky secret create

Select httpauth as the secret type and follow the prompts to provide a header name and value. For example, you might set the header name to Authorization and the value to Bearer <your-token>.

Secret names can only contain alphanumeric characters, underscores (_), and hyphens (-).

Then reference the secret in your webhook sink configuration:

sinks:
  my_webhook_sink:
    type: webhook
    from: my_transform
    url: https://api.example.com/endpoint
    secret_name: MY_WEBHOOK_SECRET

The header name and value from the secret are automatically added to every request sent to the webhook endpoint. Setting the same header explicitly under headers alongside secret_name is a configuration error — remove one.

Example: Send High-Value Transfers to API

transforms:
  high_value_transfers:
    type: sql
    primary_key: id
    sql: |
      SELECT *
      FROM erc20_transfers
      WHERE CAST(value AS DECIMAL) > 1000000000000000000000

sinks:
  webhook_alerts:
    type: webhook
    from: high_value_transfers
    url: https://alerts.example.com/high-value-transfer
    secret_name: ALERTS_API_SECRET
    one_row_per_request: true

Delivery and retries

At-least-once delivery. Your endpoint may receive duplicates after retries; use primary_key or an idempotency key on the receiving side if duplicates are a problem.
Retriable responses — network errors, request timeouts, 408 Request Timeout, 429 Too Many Requests, and any 5xx — are retried indefinitely with exponential backoff.
Non-retriable responses (other 4xx errors) fail the pipeline immediately.
Backpressure. The pipeline paces delivery to your endpoint’s responsiveness, so a slow receiver slows the pipeline rather than dropping data.

​Overview

​Configuration

​Parameters

​Request Format

​Secret creation

​Example: Send High-Value Transfers to API

​Delivery and retries

Overview

Configuration

Parameters

Request Format

Secret creation

Example: Send High-Value Transfers to API

Delivery and retries