Skip to main content

Webhook Integration

Webhooks notify your application when blockchain operations complete. Instead of polling, receive HTTP callbacks with event data.

Register an Endpoint​

const endpoint = await urblock.webhooks.create({
  url: "https://example.com/webhooks/urblock",
  events: [
    "token.deployed",
    "transaction.confirmed",
    "transaction.failed",
  ],
});

Common Event Types​

The most frequently used event types are listed below. For the complete list of all 55+ event types, see the Webhooks API reference.

EventDescription
token.deployedToken contract deployed on-chain
transaction.confirmedTransaction confirmed
transaction.failedTransaction failed
token.mintedToken minted
token.transferredToken transferred
token.burnedToken burned
token.approvedToken approval set
token.pausedToken paused
token.unpausedToken unpaused
nft.mintedNFT minted
nft.transferredNFT transferred
nft.burnedNFT burned
nft.metadata_updatedNFT metadata updated
token.frozenT-REX address frozen
token.unfrozenT-REX address unfrozen
token.force_transferredT-REX forced transfer
token.recoveredT-REX identity recovery
role.grantedRole granted
role.revokedRole revoked

Webhook Payload​

{
  "object": "event",
  "id": "evt_abc123",
  "type": "transaction.confirmed",
  "data": {
    "object": "transaction",
    "id": "tx_xyz789",
    "status": "confirmed",
    "tx_hash": "0x...",
    "block_number": 12345678
  },
  "created": 1709740800
}

Signature Verification​

Every webhook request includes an X-Urblock-Signature header signed with HMAC-SHA256. Verify it to ensure the request came from Urblock:

import crypto from "node:crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

List Endpoints​

const endpoints = await urblock.webhooks.list();

Delete an Endpoint​

await urblock.webhooks.delete("whe_abc123");

List Events​

Query past events:

const events = await urblock.events.list({ limit: 20 });

Best Practices​

  1. Verify signatures — always validate X-Urblock-Signature
  2. Return 2xx quickly — process events asynchronously
  3. Handle retries — Urblock retries failed deliveries with exponential backoff (5 attempts)
  4. Idempotency — use the evt_ ID to deduplicate events

Next Steps​