Webhooks

Webhooks provide real-time updates about the status of provenance registrations. They allow your application to track the complete lifecycle of a registration from initial submission through blockchain confirmation and NFT creation.

Overview

When registering provenance claims, the process involves several asynchronous steps:

1. File download and hash calculation (if a file URL is provided)
2. Blockchain transaction submission
3. Transaction confirmation
4. NFT creation and metadata storage

Webhooks notify your application as each step completes, allowing you to track progress and update your users accordingly.

Event Types

Each registrar receives webhooks for all registrations made through their account, whether via API or manual registration. There are two categories of events:

Standard Events

These events fire for all registrations associated with your registrar:

• provenance.registration.complete - Fired when a registration is confirmed on-chain
• provenance.registration.nft_added - Fired when an NFT is successfully attached to the registration

Extended Events

These additional events fire only for registrations made through the API:

• provenance.registration.hashed - Fired when the file hash has been calculated
• provenance.registration.submitted - Fired when the transaction is submitted to the blockchain

Event Payloads

provenance.registration.hashed

Fired after downloading and hashing the provided file:

{
  type: "provenance.registration.hashed",
  data: {
    context?: any,  // Your original context object if provided
    provenance: {
      content_hash: string  // The Blake3 hash of the content
    }
  }
}

provenance.registration.submitted

Fired when the registration transaction is submitted:

{
  type: "provenance.registration.submitted",
  data: {
    context?: any,  // Your original context object if provided
    provenance: {
      content_hash: string
    },
    transaction: {
      transaction_hash: string  // The blockchain transaction hash
    }
  }
}

provenance.registration.complete

Fired when the registration is confirmed on-chain:

{
  type: "provenance.registration.complete",
  data: {
    context?: any,  // Your original context object if provided
    provenance: {
      content_hash: string,
      id: string,
      originator: {
        number: string,    // Royal ID as decimal string
        username: string
      },
      registrar: {
        number: string,    // Royal ID as decimal string
        username: string
      }
    },
    transaction: {
      transaction_hash: string,
      block_hash: string,
      block_number: number,
      chain_id: number,
      log_index: number,
      transaction_index: number,
      removed: boolean
    }
  }
}

provenance.registration.nft_added

Fired when an NFT is attached to the registration:

{
  type: "provenance.registration.nft_added",
  data: {
    context?: any,  // Your original context object if provided
    provenance: {
      content_hash: string,
      id: string,
      originator: {
        number: string,
        username: string
      },
      registrar: {
        number: string,
        username: string
      },
      nft: {
        address: string,  // NFT contract address
        id: string       // Token ID as decimal string
      }
    },
    transaction: {
      transaction_hash: string,
      block_hash: string,
      block_number: number,
      chain_id: number,
      log_index: number,
      transaction_index: number,
      removed: boolean
    }
  }
}

Webhook Delivery

Royal uses Svix 🔗 for reliable webhook delivery. This provides:

• Automatic retries for failed deliveries
• Webhook signature verification
• Delivery logs and debugging tools

For details on implementing webhook consumers, including signature verification and best practices, see the Svix documentation 🔗.

Context Object

When making API calls, you can include a context object containing arbitrary JSON data. This same object will be included in all webhook events related to that registration. This allows you to correlate webhook events with your application’s data.

For example, you might include your internal user ID or transaction reference:

{
  "context": {
    "user_id": "12345",
    "transaction_ref": "tx_abc123"
  }
}

This context will be included in all webhooks related to this registration.

Best Practices

1. Verify Signatures: Always verify webhook signatures using the Svix library to ensure authenticity.
2. Handle Duplicates: While rare, webhooks may be delivered multiple times. Design your handlers to be idempotent.
3. Store Context: Include meaningful context data when registering claims to help correlate webhooks with your application state.
4. Monitor Progress: Use webhooks to provide progress updates to your users as their registration moves through the pipeline.
5. Log Events: Store webhook events for debugging and audit purposes.