Handle Timestamping as a Client

This guide explains how to interact with the OriginStamp API as a client to timestamp data, track verification progress, and respond to blockchain confirmations via webhooks.

Overview

When you timestamp data using the OriginStamp API, the data is hashed, grouped into Merkle trees, and later anchored in one or more blockchains (e.g., Bitcoin, Ethereum). To track this lifecycle, the API returns a unique identifier called the treeId, i.e. just the identification of the Merkle Tree the hash is anchored to.

As a client, it's essential to:

1. Timestamp your data via the API.
2. Save the treeId values returned for each supported blockchain you want to utilize.
3. Listen for webhook notifications to know when your timestamp has been verified on-chain.

Set your Webhook settings

To receive notifications about the verification status of your timestamps, set up a webhook URL in your API key settings.

Step 1: Timestamp your data

Refer to our Getting Started Guide for a quick introduction on how to use the API and get familiar with authentication and basic setup instructions.

A typical response for new timestamps will look like this:

{
    "sha256": [
        "2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e"
    ],
    "dateCreated": 1751637581512,
    "trees": [
        {
            "treeId": "4dc4c401-5a55-48ee-802c-3f1659b10aa5",
            "currencyId": 0,
            "currency": "BTC"
        },
        {
            "treeId": "c7a8d8c9-7b29-49ee-bd33-9c8b5cb4445a",
            "currencyId": 1,
            "currency": "ETH"
        }
    ]
}

Save the treeId values (either for BTC and ETH or both). These are essential for tracking when your data is officially recorded on-chain.

Step 2: Understand the Verification Lifecycle

Each treeId represents a Merkle tree of timestamped hashes submitted to a blockchain. Once a block is mined and includes the anchored hash, OriginStamp will mark the submitStatus of a tree as verified.

OriginStamp will then trigger a webhook to notify you that verification has occurred. This is usually done every 24 hours.

You must track the treeId per blockchain because:

• Each blockchain submits hashes independently.
• Confirmation times differ.
• Verification webhooks are triggered per blockchain tree.

Step 3: Handle Webhook Notifications

Set up a webhook endpoint to receive real-time notifications when a tree is verified. You can test these webhooks in our API Reference (opens new window).

Webhook payload example:

{
  "treeId": "4dc4c401-5a55-48ee-802c-3f1659b10aa5",
  "currencyId": 0,
  "currency": "BTC",
  "submitStatus": 3,
  "timestamp": 1710000000000,
  "rootHash": "dc19dddc4e9f8742e31cbbaafe894daa01760f32b11d5cce29224981cef4ba1b",
  "transactionHash": "9f2c93c0edc444f17e6a96c771f34243c0978be4cf90c5d33bb8bfb5a1e5a4f3"
}

Your system should:

• Match the treeId to your original request.
• Mark the timestamp as verified.
• Optionally notify your users or update audit logs

What to do when you did not receive a webhook

If you did not receive a webhook notification in the next 24 hours, you can check the status of the associated Merkle Tree directly. Please abstain from polling the API for verification status, as this is inefficient and can lead to rate limiting.

Summary

To effectively use OriginStamp as a client:

1. Timestamp your hash and request specific blockchains.
2. Save the returned treeIds for each blockchain.
3. Track verification by listening for webhooks.
4. React to verified timestamps as needed.

This enables a reliable verification cycle and allows your users to prove their data was anchored in a public blockchain at a specific point in time.