Webhooks - Soran

Webhooks send namespace events to your backend. Open Developer tools in the console, enter a public HTTPS endpoint, choose your events and save the signing secret shown at creation. Private or internal endpoints are rejected.

Event types

Event	Fires when
`issued`	A name is issued in your namespace (on-chain event)
`reclaimed`	A name is reclaimed from its holder (on-chain event)
`transferred`	A name changes holders (on-chain event)
`went_cold`	The hosted service marks a name dormant/cold; this is not proof of on-chain archival
`invoice_paid`	A subscription invoice payment was matched
`entitlement_suspended`	The subscription was suspended, typically after an ownership transfer pending re-attestation
`entitlement_resumed`	A suspended subscription came back
`entitlement_lapsed`	The subscription period ended unpaid
`market_listed` / `market_sold` / `market_refunded`	Marketplace lifecycle for your namespace

Billing and marketplace events apply only when enabled on a deployment. Both features are disabled on the current testnet setup. This table lists the supported subscriptions. For other contract events, including payment, text, fee and renewal events, use the event archive.

Delivery format

Each delivery is a POST with a JSON body:

{
  "event": "issued",
  "namespace": "yourbrand",
  "data": { "name": "alice.yourbrand", "...": "..." },
  "id": "wd_4f0c2e..."
}

Each request includes these headers. The signature is an HMAC-SHA256 digest of the raw body:

x-soran-event: issued
x-soran-signature: sha256=8f3b2a…

Deduplicate deliveries by id. For a given subscription and on-chain event, the ID stays the same even after an indexer replay.

Verify the signature

Your whsec_… signing secret is shown once and cannot be retrieved later. Keep it on your backend. Verify each request before processing it:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifySoranWebhook(rawBody: Uint8Array, signatureHeader: string, secret: string): boolean {
  const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
  const a = new TextEncoder().encode(signatureHeader);
  const b = new TextEncoder().encode(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Pass the raw body bytes from your HTTP framework. Parsing and re-serializing JSON can change those bytes and invalidate the signature.

Rotating the secret

Rotate a lost or exposed secret in Developer tools. Save the new secret when it is shown. In-flight requests may still carry the old signature, so account for that overlap and continue deduplicating by delivery ID. Authorized owners and admins can rotate secrets even when billing restricts new webhook creation.

Retries and timeouts

Return a 2xx within 8 seconds. Other responses and timeouts count as failures.
Failed requests get up to 6 attempts total, with retry backoff of approximately 2, 4, 8, 16 and 32 seconds. Scheduling and request time affect the actual intervals.
Deliveries run asynchronously and concurrently. Do not depend on arrival order.
Completed or failed delivery records are pruned after about two weeks. Use the event archive and its coverage to reconcile missed events.

Verify the signature, deduplicate the ID, enqueue your work and return 200 promptly. Process the event outside the request handler.

When billing is enabled on a deployment, creating a webhook requires an active subscription. Existing webhooks keep delivering, and signing-secret rotation stays available.

​Event types

​Delivery format

​Verify the signature

​Rotating the secret

​Retries and timeouts

Event types

Delivery format

Verify the signature

Rotating the secret

Retries and timeouts