API Key settings

Via the OriginStamp API you can also manage your API key settings to:

• Configure your webhook URL.
• Monitor your usage (requests, timestamps, verifications).

This page explains how to configure these features via API calls.

Webhook notifications

Use the following endpoint to set or update webhook targets for both proof and tree verification events.

Endpoint and Headers:

PATCH /v1/api-key/setting
x-api-key: YOUR_API_KEY
Content-Type: application/json

Request:

{
  "notification": {
    "proof": {
      "target": "https://yourdomain.com/webhooks/proof"
    },
    "tree": {
      "target": "https://yourdomain.com/webhooks/tree"
    }
  }
}

Set an empty string ("") as the target to deactivate a webhook.

Both proof and tree fields are optional - but can be updated separately or at the same time.

If you only want to update one of the two, you can omit the other field in the request.

{
  "notification": {
    "proof": {
      "target": "http://yourdomain.com/proof/endpoint"
    }
  }
}

And if you want to remove a webhook, you can set the target to an empty string:

{
  "notification": {
    "proof": {
      "target": ""
    }
  }
}

The endpoint will always respond with all settings:

{
    "notification": {
        "proof": {
            "target": ""
        },
        "tree": {
            "target": "https://yourdomain.com/webhooks/tree"
        }
    }
}

You can test the payload for webhooks and how your system handles them in our API Reference (opens new window) as explained also in the webhook section.

Usage Overview

You can monitor how many timestamps, proofs, and status requests you've used in a given month.

Endpoint and Headers:

POST /v1/api-key/usage
x-api-key: YOUR_API_KEY
Content-Type: application/json

Request:

{
  "year": 2025,
  "month": 6
}

Month is one-based (i.e., 1 = January, 7 = July).

Response:

{
  "limitTimestamps": 1000,
  "limitProofs": 100,
  "limitStatus": 500,
  "reports": [
    {
      "year": 2025,
      "month": 6,
      "usedTimestamps": 542,
      "usedProofs": 21,
      "usedStatus": 101
    }
  ]
}

If you want to check your usage for the current year, you can omit the month field in the request:

{
  "year": 2025
}

{
  "limitTimestamps": 1000,
  "limitProofs": 100,
  "limitStatus": 500,
  "reports": [
    {
      "year": 2025,
      "month": 6,
      "usedTimestamps": 542,
      "usedProofs": 21,
      "usedStatus": 101
    },
    {
      "year": 2025,
      "month": 5,
      "usedTimestamps": 411,
      "usedProofs": 67,
      "usedStatus": 89
    },
    ...
  ]
}