Ctrlk
Go to websiteDashboard
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Delivery Format

The HTTPS request a GetBlock webhook sends to your endpoint: headers, response rules, payload fields, example events and test deliveries.

Every delivery is one HTTPS POST to your webhook's target_url with one event as its JSON body.

The request

POST <target_url>
Content-Type: application/json
User-Agent: GetBlock-Webhooks/1
X-GetBlock-Signature: t=1789455600,v1=663d17a7e5aa07ca7df21050f7688cc54a78e4fa9cfbb5d1774e4df5e31822d4

  • These three headers are the ones GetBlock sets; the usual transport headers (Host, Content-Length, Accept-Encoding) come with them. How to check X-GetBlock-Signature is on Verifying Signatures.

  • The body is one event as uncompressed JSON. There is no batching and no Content-Encoding.

  • Your endpoint must present a valid TLS certificate for its host name.

  • Answer with any 2xx within 15 seconds (5 seconds to connect and finish the TLS handshake). The response body is not used; at most 4 KiB of it is read.

  • Redirects are never followed: a 3xx answer is a failed attempt.

Anything other than a 2xx in time is retried. See Retries and Endpoint Protection.

Payload fields

Field
Type
Meaning

webhookId

string

The webhook (wh_…)

eventId

string

The event's identity, the same in an event and its reorg correction. Opaque: compare it as a string, do not parse it

type

string

address_activity, log_event or tx_confirmation

network

string

The network, for example eth-mainnet

confirmed

boolean

false — first inclusion in a block; true — the block reached the confirmation depth

removed

boolean

true — reorg correction: the block holding this event left the canonical chain

block

object

number (hex), hash and an optional timestamp (hex)

raw

object

The log or transaction exactly as the node returned it

decoded

object, optional

event, signature and params (name → value; {} when the event has no parameters). Present for ERC-20 Transfer and Approval

  • Optional keys are left out, never sent as null.

  • confirmed and removed are never both true.

  • Numbers are hex strings, as the node returns them.

Example

An ERC-20 Transfer delivered by a log_event webhook that takes both phases. The three deliveries of one event share the same eventId:

The confirmed delivery is identical to the unconfirmed one except "confirmed": true. The correction carries the same eventId and payload with "removed": true. What to do with each is on Handling Chain Reorganizations.

Other triggers

A native ETH transfer to or from a watched address. A token transfer of a watched address arrives as the token's log, with decoded for ERC-20:

raw is the transaction and eventId refers to the block it was mined in; block is the newer block at which the transaction reached confirm_depth:

Test deliveries

A test event (Send test event in the dashboard, or POST /api/v1/webhooks/{id}/test) is a delivery of the webhook's own event type, signed with the webhook's secrets and sent to its URL with the same retries and protection as a live event.

  • The data is sample mainnet data. Its eventId contains :test:, and every test is a new eventId. There is no block.timestamp, and confirmed is true.

  • Test deliveries are free, and are sent even when your CU balance is zero.

  • Only an active webhook can be tested: otherwise the answer is 409 webhook_not_active.

  • 503 test_event_unavailable means the test could not be confirmed as queued in time; it may still arrive. Another request sends a second, separate test event.

  • A successful test delivery shows in the webhook's stats (delivered_total), not in the delivery history, which lists failed attempts only.

  • Test deliveries count like any other delivery for the circuit breaker and auto-pause: repeated tests against an endpoint that fails bring an automatic pause closer.

PreviousTriggers and Filters
NextVerifying Signatures

Last updated

Was this helpful?