Webhooks Overview

Webhooks send real-time notifications to your server when events occur (e.g., a transaction is confirmed, a token is deployed). Instead of polling the API, your server receives a POST request the moment something happens.

How It Works

1. Register a webhook endpoint → POST /v1/webhook_endpoints
2. Subscribe to event types (e.g., "token.deployed", "transaction.confirmed")
3. Urblock sends POST requests with signed JSON payloads to your endpoint
4. Your server responds with 2xx to acknowledge receipt
5. Failed deliveries are retried with exponential backoff

Payload Format

Every webhook delivery sends a JSON body with this structure:

{
  "object": "event",
  "id": "evt_abc123",
  "type": "transaction.confirmed",
  "data": {
    "object": "transaction",
    "id": "tx_abc123",
    "type": "mint",
    "status": "confirmed",
    "tx_hash": "0xabc...",
    "token_id": "tok_abc123",
    "created": 1709740800
  },
  "created": 1709740860
}

Delivery Headers

Each delivery includes these headers:

Header	Description
X-Urblock-Event	Event type (e.g., transaction.confirmed)
X-Urblock-Delivery	Unique delivery ID (whd_...)
X-Urblock-Signature	HMAC-SHA256 signature for verification
Content-Type	Always application/json

Signature Verification

Every delivery is signed with your webhook secret using HMAC-SHA256. The signature format is:

X-Urblock-Signature: t=1709740860,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verification Steps

1. Extract t (timestamp) and v1 (signature) from the header
2. Build the payload: {timestamp}.{raw_body}
3. Compute HMAC-SHA256 with your webhook secret
4. Compare using constant-time comparison

Node.js Verification Example

import crypto from "crypto";

function verifySignature(rawBody: string, signatureHeader: string, secret: string): boolean {
  const [tPart, v1Part] = signatureHeader.split(",");
  const timestamp = tPart.split("=")[1];
  const receivedHmac = v1Part.split("=")[1];

  const payload = `${timestamp}.${rawBody}`;
  const expectedHmac = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(receivedHmac, "hex"),
    Buffer.from(expectedHmac, "hex")
  );
}

Timestamp Tolerance

Check that the timestamp is within 5 minutes of the current time to prevent replay attacks:

const tolerance = 5 * 60; // 5 minutes
const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
if (age > tolerance) throw new Error("Webhook too old");

Retry Policy

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff:

Attempt	Delay	Total wait
1	Immediate	0s
2	30s	30s
3	2 min	2.5 min
4	8 min	10.5 min
5	32 min	42.5 min

After 5 failed attempts, the delivery is marked as failed. You can manually retry failed deliveries via the Webhooks API.

Event Types

Event Type	Description
token.deployed	Token contract confirmed on-chain
token.deploy_failed	Token deployment failed
transaction.submitted	Transaction sent to blockchain
transaction.confirmed	Transaction confirmed in a block
transaction.failed	Transaction reverted or timed out
identity.registered	T-REX identity registered
compliance.module_bound	Compliance module bound to token
governance.proposal_created	New governance proposal
governance.proposal_executed	Proposal executed via timelock
vesting.deployed	Vesting contract deployed
vault.deployed	Vault contract deployed
multisig.deployed	Multisig wallet deployed
tba.created	Token Bound Account created
batch.completed	Batch operation completed

Best Practices

1. Always verify signatures — never trust unverified payloads
2. Respond quickly — return 200 OK before doing heavy processing; queue work for later
3. Handle duplicates — use the id field (event ID) to deduplicate in your handler
4. Use HTTPS — webhook URLs must use HTTPS
5. Monitor failures — check the delivery dashboard for failed webhooks
6. Process idempotently — your handler should be safe to call multiple times with the same event

Next Steps

• Webhooks API — CRUD endpoints for webhook management
• Events API — query historical events
• Webhook Integration Guide — step-by-step setup
• Idempotency — handle duplicate deliveries safely