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. Managing endpoints requires webhooks:write; reading endpoints and deliveries requires webhooks:read.

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
`build.blank.launch.created.v1`	A launch record is created
`build.blank.launch.confirmed.v1`	A launch is confirmed on-chain
`build.blank.trade.confirmed.v1`	A trade is confirmed
`build.blank.staking.position.updated.v1`	A staking position changes
`build.blank.fee.distribution.created.v1`	A fee distribution is booked
`build.blank.prediction.submitted.v1`	A price prediction is accepted
`build.blank.prediction.round.locked.v1`	A prediction round locks
`build.blank.prediction.round.settled.v1`	A prediction round settles
`build.blank.presale.updated.v1`	Presale state changes
`build.blank.audience-export.completed.v1`	An audience export finishes
`build.blank.operation.failed.v1`	An asynchronous operation fails

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.round.locked.v1",
    "build.blank.prediction.round.settled.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.round.settled.v1",
  "subject": "round: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.

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

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

​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

Verifying the signature

Responding

Retries and dead letters

Inspecting deliveries

Replaying

Rotating the signing secret

Updating and deleting

Errors