Webhooks

Blank delivers events to your HTTPS endpoint as signed CloudEvents 1.0 JSON. Webhooks replace polling for anything you need to react to promptly. Webhooks need an API key. Creating, updating, deleting, rotating and replaying require a key with webhooks:write; reading endpoints and deliveries requires webhooks:read. This holds even when every read you care about is anonymous, such as staking or token data.

Limits

Limit	Value	Exceeding it
Endpoints per account	20	`409 webhook_endpoint_limit_reached` — delete one first
Replays per delivery	10	`409 webhook_delivery_replay_limit_reached`
Deliveries claimed per batch	10	No error; the rest are claimed in the next dispatch pass

Deleted endpoints do not count toward the endpoint limit. The per-batch figure is a fair-share bound rather than a quota: dispatch takes at most that many of your deliveries per pass so one account’s backlog cannot delay everyone else’s, and your remaining deliveries are picked up on subsequent passes in the usual order.

Operations

Operation	HTTP	SDK	Scope	Success
`createWebhookEndpoint`	`POST /webhook-endpoints`	`blank.webhooks.create(input, options)`	`webhooks:write`	`201`
`listWebhookEndpoints`	`GET /webhook-endpoints`	`blank.webhooks.list(query)`	`webhooks:read`	`200`
`getWebhookEndpoint`	`GET /webhook-endpoints/{endpointId}`	`blank.webhooks.get(endpointId)`	`webhooks:read`	`200`
`updateWebhookEndpoint`	`PATCH /webhook-endpoints/{endpointId}`	`blank.webhooks.update(endpointId, input, options)`	`webhooks:write`	`200`
`deleteWebhookEndpoint`	`DELETE /webhook-endpoints/{endpointId}`	`blank.webhooks.delete(endpointId, version, options)`	`webhooks:write`	`200`
`rotateWebhookSecret`	`POST /webhook-endpoints/{endpointId}/secret-rotations`	`blank.webhooks.rotateSecret(endpointId, input, options)`	`webhooks:write`	`201`
`listWebhookDeliveries`	`GET /webhook-endpoints/{endpointId}/deliveries`	`blank.webhooks.deliveries(endpointId, query)`	`webhooks:read`	`200`
`replayWebhookDelivery`	`POST /webhook-deliveries/{deliveryId}/replays`	`blank.webhooks.replay(deliveryId, options)`	`webhooks:write`	`202`

All mutations require an Idempotency-Key. Update, delete, and rotate additionally require If-Match with the endpoint’s current version.

Event types

Event type	Fires when	Status
`build.blank.prediction.submitted.v1`	A price prediction is accepted	Delivered
`build.blank.trade.confirmed.v1`	A trade is indexed	Delivered
`build.blank.staking.position.updated.v1`	A staking position changes	Delivered
`build.blank.launch.created.v1`	A launch lands on chain	Delivered
`build.blank.launch.confirmed.v1`	A launch starts trading on its bonding curve	Delivered
`build.blank.fee.distribution.created.v1`	A fee distribution is recorded	Delivered
`build.blank.prediction.round.locked.v1`	A prediction round locks	Delivered
`build.blank.prediction.round.settled.v1`	A prediction round settles	Delivered
`build.blank.operation.failed.v1`	An asynchronous operation fails	Delivered
`build.blank.presale.updated.v1`	A presale’s public state changes	Reserved, not available yet
`build.blank.audience-export.completed.v1`	An audience export finishes	Reserved, not available yet

An endpoint can subscribe to a reserved type, and the subscription is accepted, but Blank sends nothing for it until the type ships. Until then, poll the matching read: GET /presales/{id} for presales. The API has no audience export yet. prediction.submitted and operation.failed go only to endpoints owned by the account that submitted the prediction or owns the operation. Every other delivered type is a public market event: every active endpoint subscribed to the type receives it, for every visible token. Hidden tokens send nothing. Types are versioned with a .v1 suffix. A breaking payload change ships as a new type, never as a mutation of an existing one.

Create an endpoint

const created = await blank.webhooks.create({
  name: "prediction-bot",
  url: "https://hooks.example.com/blank",
  eventTypes: ["build.blank.prediction.submitted.v1"],
});

console.log(created.data.endpoint.id);
console.log(created.data.secret); // whsec_... — shown once

Field	Rules
`name`	1–80 characters
`url`	HTTPS only, see the URL policy below
`eventTypes`	1 to 11 values from the table above

The signing secret is returned exactly once, at creation and at rotation. Store it in your secret manager immediately. If you lose it, rotate — there is no way to read it back.

URL policy

Endpoint URLs are validated at creation and again on every delivery attempt. A URL is rejected with 422 webhook_url_disallowed unless it:

uses https: on the default port (no port, or 443)
carries no userinfo and no fragment
resolves to a public, fully qualified hostname — not localhost, and not a hostname ending in .localhost, .local, .internal, .home.arpa, or .onion
is not a private, loopback, link-local, carrier-grade NAT, documentation, or multicast IP address, in IPv4 or IPv6

Redirects are followed at most three times, and every hop is re-validated against the same policy.

The delivery request

Blank sends POST with these headers:

Header	Value
`Content-Type`	`application/json; charset=utf-8`
`Blank-Event-Id`	Immutable event UUID — use it to deduplicate
`Blank-Delivery-Id`	This delivery attempt’s UUID
`Blank-Event-Type`	The event type
`Blank-Signature`	`t=<unix seconds>,v1=<hex>` (plus `v0=<hex>` during rotation)
`Blank-Webhook-Version`	`2026-08-01`

The body is a CloudEvent:

{
  "specversion": "1.0",
  "id": "b7a1f7f0-9d0b-4a5a-8f2f-9a3f1c2d4e5f",
  "source": "https://api.blank.build",
  "type": "build.blank.prediction.submitted.v1",
  "subject": "prediction/24c85940-7968-4b71-92dd-0d8f017cea5a",
  "time": "2026-08-10T12:00:00.000Z",
  "datacontenttype": "application/json",
  "data": {}
}

data carries the allowlisted payload for that event type. Treat unknown fields as additive and ignore them.

Event payloads

`build.blank.trade.confirmed.v1`

Sent once for each trade Blank indexes on a visible token. subject is token_trade/{id}, and data is the same Trade object that GET /tokens/{mint}/trades returns. A trade the indexer sees again, for example after a retry, sends nothing.

{
  "specversion": "1.0",
  "id": "0f4c1c1e-6a52-4a8e-9a57-3c2d7f0c9b11",
  "source": "https://api.blank.build",
  "type": "build.blank.trade.confirmed.v1",
  "subject": "token_trade/b59939f5-8f4f-4cf0-b6f3-e49d052d2151",
  "time": "2026-09-30T10:21:33.412Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "b59939f5-8f4f-4cf0-b6f3-e49d052d2151",
    "type": "buy",
    "traderWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "mintAddress": "49xGqHYKHPqLsFKKo7zctBQrnw6Ky3SSamHWutWhBLNK",
    "tokenAmount": "1234.5",
    "solAmount": "0.12345679",
    "pricePerTokenInSol": "0.0001",
    "transactionSignature": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
    "slot": "123456789",
    "blockTime": "2026-09-30T10:21:32.123Z"
  }
}

`build.blank.staking.position.updated.v1`

Sent when Blank indexes a new staking position, a change to one, or its removal. subject is staking_position/{id}. data.change says which:

`change`	Sent when
`opened`	A position is indexed for the first time.
`updated`	An indexed position’s amount, weighted amount, lock, funder, or transaction signature changes.
`closed`	A position is fully unstaked and removed.

data.position is the StakingPosition object that blank.staking.walletPositions() returns, as of the change, without the reward fields (pendingRewardsLamports, totalRewardsClaimedLamports, claimable, rewardsAsOf). Rewards are read live from chain, so call walletPositions() when you need them. A closed position carries its last indexed values with amountRaw and weightedAmountRaw set to "0", and updatedAt set to the time it was removed. Re-indexing a position without a change sends nothing.

{
  "specversion": "1.0",
  "id": "7d0e5d3a-2f7b-4c0e-8f7a-1f7f4c2b9e63",
  "source": "https://api.blank.build",
  "type": "build.blank.staking.position.updated.v1",
  "subject": "staking_position/515b810e-2a49-43d5-80c8-743b1f345eec",
  "time": "2026-09-30T11:00:58.300Z",
  "datacontenttype": "application/json",
  "data": {
    "change": "updated",
    "position": {
      "id": "515b810e-2a49-43d5-80c8-743b1f345eec",
      "mintAddress": "49xGqHYKHPqLsFKKo7zctBQrnw6Ky3SSamHWutWhBLNK",
      "ownerWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "funderWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "positionIndex": "0",
      "amountRaw": "2500000000",
      "weightedAmountRaw": "3750000000",
      "lockPeriod": "month",
      "lockStart": "2026-09-30T00:00:00.000Z",
      "lockEnd": "2026-10-30T00:00:00.000Z",
      "transactionSignature": "4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZAMdL4VZHirAn6BaN4CfTbnNHEb4pC7zE5jDD3Zdv9fTBxdxPT3P9BUwg",
      "updatedAt": "2026-09-30T11:00:58.109Z"
    }
  }
}

`build.blank.launch.created.v1` and `build.blank.launch.confirmed.v1`

subject is token_launch/{id}, and data is the Token object that GET /tokens/{mint} returns at the moment of the change. Each is sent at most once per token.

Event	Sent when
`launch.created`	The launch is on chain. For a bonding-curve launch that is when its launch transaction confirms, together with `launch.confirmed`. For a Pre-Raise launch it is when the raise setup confirms (`status` `pre_raise_pending` or `pre_raising`).
`launch.confirmed`	A bonding-curve launch is live and trading (`status` `bonding`). Pre-Raise launches never bond, so they do not send it; poll `GET /presales/{id}` to follow the raise.

A launch that is still waiting for its creator’s signature sends nothing: it may never reach the chain. A token that is hidden when it launches sends neither event.

{
  "specversion": "1.0",
  "id": "3b9c1e44-51e9-4a53-a0f5-0c2b3e7d9a10",
  "source": "https://api.blank.build",
  "type": "build.blank.launch.confirmed.v1",
  "subject": "token_launch/0d53c99c-e07b-4c0b-8c8b-8fce5fc8943b",
  "time": "2026-09-30T12:17:41.020Z",
  "datacontenttype": "application/json",
  "data": {
    "mintAddress": "49xGqHYKHPqLsFKKo7zctBQrnw6Ky3SSamHWutWhBLNK",
    "name": "Blank Token",
    "symbol": "BLNK",
    "description": "The token for the Blank community.",
    "imageUrl": "https://images.blank.build/49xGqHYKHPqLsFKKo7zctBQrnw6Ky3SSamHWutWhBLNK.png",
    "status": "bonding",
    "launchType": "dbc",
    "creatorWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "currentPriceInSol": "0.000000028",
    "solCollectedInSol": "0",
    "totalSupply": "1000000000",
    "launchedAt": "2026-09-30T12:17:40.355Z",
    "graduatedAt": null,
    "decimals": 6,
    "marketCapInSol": "28",
    "links": {
      "website": "https://blank.build/",
      "twitter": "https://x.com/blank",
      "telegram": null
    }
  }
}

`build.blank.fee.distribution.created.v1`

Sent once for each fee distribution Blank records on a visible token. subject is fee_distribution/{id}, and data is the item that GET /tokens/{mint}/fee-distributions returns, plus the token’s mintAddress, since the item alone does not name the token. A distribution the indexer sees again sends nothing.

{
  "specversion": "1.0",
  "id": "8a1f2c3d-4e5f-4a6b-9c7d-8e9f0a1b2c3d",
  "source": "https://api.blank.build",
  "type": "build.blank.fee.distribution.created.v1",
  "subject": "fee_distribution/b5590695-eeac-44fb-af42-06b7262cdf0f",
  "time": "2026-09-30T12:00:01.500Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "b5590695-eeac-44fb-af42-06b7262cdf0f",
    "feeType": "trade",
    "recipient": "creator",
    "amountInSol": "0.00123457",
    "transactionSignature": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
    "slot": "424242",
    "collectedAt": "2026-09-30T12:00:00.123Z",
    "mintAddress": "49xGqHYKHPqLsFKKo7zctBQrnw6Ky3SSamHWutWhBLNK"
  }
}

`build.blank.prediction.round.locked.v1` and `build.blank.prediction.round.settled.v1`

subject is prediction_round/{id}, and data is the PredictionRound object that GET /tokens/{mint}/prediction-rounds/{roundId} returns. round.locked is sent once when the round stops taking predictions, and round.settled once when its settlement price and ranks are final. A settlement that fails and is retried does not send a second round.locked. predictionCount in round.locked counts the predictions recorded when the round locked.

{
  "specversion": "1.0",
  "id": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
  "source": "https://api.blank.build",
  "type": "build.blank.prediction.round.settled.v1",
  "subject": "prediction_round/f82e8ae7-3181-49bf-be16-bee72f24caf5",
  "time": "2026-10-01T00:05:01.200Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "f82e8ae7-3181-49bf-be16-bee72f24caf5",
    "mintAddress": "49xGqHYKHPqLsFKKo7zctBQrnw6Ky3SSamHWutWhBLNK",
    "roundNumber": 20725,
    "status": "settled",
    "opensAt": "2026-09-29T00:00:00.000Z",
    "locksAt": "2026-09-30T00:00:00.000Z",
    "settlementWindowStart": "2026-09-30T20:00:00.000Z",
    "settlementWindowEnd": "2026-10-01T00:00:00.000Z",
    "baselinePriceInSol": "0.00000003",
    "settlementPriceInSol": "0.000000031",
    "prizePoolLamports": "5000000",
    "predictionCount": 12,
    "settledAt": "2026-10-01T00:05:00.000Z"
  }
}

`build.blank.operation.failed.v1`

Sent once when one of your asynchronous operations fails, and only to endpoints owned by the account that owns the operation. subject is api_operation/{id}, and data is the Operation object that GET /operations/{operationId} returns, with the Problem Details of the failure in error.

{
  "specversion": "1.0",
  "id": "5f4e3d2c-1b0a-4987-8654-3210fedcba98",
  "source": "https://api.blank.build",
  "type": "build.blank.operation.failed.v1",
  "subject": "api_operation/24c85940-7968-4b71-92dd-0d8f017cea5a",
  "time": "2026-09-30T12:00:05.100Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "24c85940-7968-4b71-92dd-0d8f017cea5a",
    "kind": "audience_export",
    "status": "failed",
    "createdAt": "2026-09-30T12:00:00.000Z",
    "startedAt": "2026-09-30T12:00:01.000Z",
    "completedAt": "2026-09-30T12:00:05.000Z",
    "resultUrl": null,
    "error": {
      "type": "https://blank.build/docs/reference/errors#internal_error",
      "title": "Internal server error",
      "status": 500,
      "detail": "The export could not be completed.",
      "instance": "/api/v2/operations/24c85940-7968-4b71-92dd-0d8f017cea5a",
      "code": "internal_error",
      "requestId": "req_0123456789abcdef0123456789abcdef"
    }
  }
}

Events are dispatched about once a minute and can arrive out of order. To rebuild state, order staking events for the same position by data.position.updatedAt, trades by data.blockTime, and fee distributions by data.collectedAt, and deduplicate on Blank-Event-Id. When you need the latest state rather than the history, read the resource from the API.

Verifying the signature

Blank-Signature is an HMAC-SHA-256 over "{timestamp}.{raw request body}", hex-encoded. Verify the exact raw bytes before parsing JSON — re-serializing the body changes the signature.

import { verifyWebhookSignature } from "@blankdotbuild/sdk";

export async function handler(request: Request): Promise<Response> {
  const rawBody = await request.text();

  const valid = await verifyWebhookSignature({
    rawBody,
    signatureHeader: request.headers.get("blank-signature") ?? "",
    secret: process.env.BLANK_WEBHOOK_SECRET!,
    previousSecret: process.env.BLANK_PREVIOUS_WEBHOOK_SECRET,
  });

  if (!valid) return new Response("invalid signature", { status: 401 });

  const event = JSON.parse(rawBody);
  await durablyAccept(event); // dedupe on event.id

  return new Response(null, { status: 204 });
}

verifyWebhookSignature enforces a timestamp tolerance of 300 seconds by default, rejecting replays outside that window. Override it with toleranceSeconds (1 to 3,600) only if you have a reason to. It checks every v1 signature against secret, and every v0 signature against previousSecret when you supply one.

Do not implement string comparison of signatures by hand. If you must verify outside the SDK, use a constant-time comparison and reject any request whose timestamp is outside your tolerance window.

Responding

Return any 2xx only after the event is durably accepted. Write it to a queue or a table first, then acknowledge.
Anything other than 2xx, a timeout, or a transport failure counts as a failed attempt and is retried.
The delivery timeout is 10 seconds. Do the work asynchronously.
Deduplicate on Blank-Event-Id. Retries and replays reuse the same event ID with a new delivery ID, and at-least-once delivery is the contract.

Retries and dead letters

Each delivery gets up to 7 attempts: the first, then six retries at roughly 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, and 24 hours. Each delay is jittered, and a Retry-After header on your response is honoured up to 24 hours. Delivery status moves through:

Status	Meaning
`pending`	Queued for its first attempt
`processing`	An attempt is in flight
`succeeded`	Your endpoint returned `2xx`
`retrying`	The attempt failed and another is scheduled
`dead_letter`	All attempts were exhausted; no further automatic delivery

Inspecting deliveries

const failed = await blank.webhooks.deliveries(endpointId, {
  status: "dead_letter",
  limit: 100,
});

for (const delivery of failed.data.data) {
  console.log(
    delivery.eventType,
    delivery.attemptCount,
    delivery.responseStatus,
    delivery.lastErrorCode
  );
}

Delivery fields: id, endpointId, eventId, eventType, status, attemptCount, nextAttemptAt, responseStatus, lastErrorCode, deliveredAt, createdAt, updatedAt. Filter by status and paginate with cursor and limit. lastErrorCode distinguishes transport failures (request_timeout, network_error, url_disallowed, redirect_limit_exceeded, redirect_location_missing) from HTTP rejections, which are recorded as http_<status>. The complete stable list is in Errors.

Replaying

const replayed = await blank.webhooks.replay(deliveryId);

A replay creates a fresh delivery for the same immutable event, with a new Blank-Delivery-Id and the original Blank-Event-Id. Use it to drain dead letters after fixing your endpoint. A delivery that is not in a replayable state returns 409 webhook_delivery_not_replayable; an unknown or foreign delivery returns 404 webhook_delivery_not_found.

Rotating the signing secret

Rotation issues a new secret and keeps the previous one valid for a bounded overlap window, so you can deploy without dropping in-flight deliveries.

const endpoint = await blank.webhooks.get(endpointId);

const rotated = await blank.webhooks.rotateSecret(endpointId, {
  overlapHours: 24,
  version: endpoint.data.version,
});

console.log(rotated.data.secret); // the new whsec_... — shown once

overlapHours is an integer from 1 to 24, defaulting to 24. During the overlap, Blank signs each delivery with both secrets: v1 with the new secret and v0 with the previous one. Safe rotation:

Rotate and store the new secret as BLANK_WEBHOOK_SECRET.
Move the old value to BLANK_PREVIOUS_WEBHOOK_SECRET and deploy, so your handler accepts both.
Once the overlap window closes, remove BLANK_PREVIOUS_WEBHOOK_SECRET.

Updating and deleting

Both use optimistic concurrency:

const endpoint = await blank.webhooks.get(endpointId);

const disabled = await blank.webhooks.update(endpointId, {
  status: "disabled",
  version: endpoint.data.version,
});

// Every successful mutation bumps the version. Use the one you just received.
await blank.webhooks.delete(endpointId, disabled.data.version);

update accepts any non-empty subset of name, url, eventTypes, and status (active or disabled). A stale version returns 412 precondition_failed — re-read the endpoint and retry. delete soft-deletes the endpoint, stops all future fanout, and returns { id, deletedAt }.

Errors

Status	Code	Meaning
404	`webhook_endpoint_not_found`	Unknown endpoint, or owned by another account
404	`webhook_delivery_not_found`	Unknown delivery, or owned by another account
409	`webhook_delivery_not_replayable`	The delivery is not in a replayable state
412	`precondition_failed`	`If-Match` did not match the current version
422	`webhook_url_disallowed`	The URL violates the endpoint URL policy
400	`cursor_invalid`	Malformed or mismatched pagination cursor

Shared errors apply too. See Errors and Conventions.

Start Here

Features

For Developers

Reference

API Reference

Endpoints

Webhooks

Webhooks

Limits

Operations

Event types

Create an endpoint

URL policy

The delivery request

Event payloads

`build.blank.trade.confirmed.v1`

`build.blank.staking.position.updated.v1`

`build.blank.launch.created.v1` and `build.blank.launch.confirmed.v1`

`build.blank.fee.distribution.created.v1`

`build.blank.prediction.round.locked.v1` and `build.blank.prediction.round.settled.v1`

`build.blank.operation.failed.v1`

Verifying the signature

Responding

Retries and dead letters

Inspecting deliveries

Replaying

Rotating the signing secret

Updating and deleting

Errors

​Webhooks

​Limits

​Operations

​Event types

​Create an endpoint

​URL policy

​The delivery request

​Event payloads

​build.blank.trade.confirmed.v1

​build.blank.staking.position.updated.v1

​build.blank.launch.created.v1 and build.blank.launch.confirmed.v1

​build.blank.fee.distribution.created.v1

​build.blank.prediction.round.locked.v1 and build.blank.prediction.round.settled.v1

​build.blank.operation.failed.v1

​Verifying the signature

​Responding

​Retries and dead letters

​Inspecting deliveries

​Replaying

​Rotating the signing secret

​Updating and deleting

​Errors

Webhooks

Limits

Operations

Event types

Create an endpoint

URL policy

The delivery request

Event payloads

`build.blank.trade.confirmed.v1`

`build.blank.staking.position.updated.v1`

`build.blank.launch.created.v1` and `build.blank.launch.confirmed.v1`

`build.blank.fee.distribution.created.v1`

`build.blank.prediction.round.locked.v1` and `build.blank.prediction.round.settled.v1`

`build.blank.operation.failed.v1`

Verifying the signature

Responding

Retries and dead letters

Inspecting deliveries

Replaying

Rotating the signing secret

Updating and deleting

Errors