Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.goldsky.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
type
string
required
Must be webhook.
​
from
string
required
Name of the transform or source to read data from.
​
url
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.
​
secret_name
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.
​
one_row_per_request
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.
​
headers
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.
​
primary_key
string
Column that uniquely identifies each row. Used for checkpointing and side-output tracking. Inherited from the upstream source or transform when omitted.

​
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.