OriginStamp Docs

# Webhooks

# What are webhooks?

A webhook (also called a web callback or HTTP push API) is an event-based notification to a specific callback URL. OriginStamp offers the possibility to activate a notification as soon as a tamper-proof timestamp of a certain crypto currency has been created. When creating the timestamp you only have to enter an URL to where the notification will be sent.

# What can webhooks be used for?

Webhooks allow you to integrate the OriginStamp API into your environment in a standardized way. Since the creation of a timestamp is limited by the block time of public blockchains and does not happen directly, the status of a hash must be polled regularly to ensure whether a file or content has already been published in the blockchain. Since a polling approach is usually more resource intensive, you can simply get notified via our webhook once the timestamp has been successfully created.

# How can I register a webhook?

To register a webhook you only have to enter the webhook address when creating a timestamp.

# Request

POST /v4/timestamp/create (opens new window)

curl -X POST "http://api.originstamp.com/v4/timestamp/create"\
     -H "Authorization: YOUR_API_KEY"\
     -H "Content-Type: application/json"\
     -d 'YOUR_PAYLOAD'

# Payload

{
  "comment": "test",
  "hash": "2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e",
  "notifications": [
    {
      "currency": 0,
      "notification_type": 1,
      "target": "https://your_url.com/originstamp/webhook"
    }
  ],
  "url": null
}

# currency

  • 0: Bitcoin
  • 1: Ethereum
  • 100: Südkurier

# notification_type

Use 1for receiving a webhook.

# target

Specify your endpoint URL that will receive and handle the webhook.

# How to receive webhooks?

Technical specifications:

  • POST Request
  • UTF-8 Encoding

Our webhooks contain the full timestamp data object that is same as used in the create and status response. A possible payload looks as follows:

# Payload

{
  "created": false,
  "date_created": 1541203188245,
  "comment": null,
  "hash_string": "2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e",
  "timestamps": [
    {
      "seed_id": "f98a61e8-22bd-4ea5-ab9e-02723ff78c40",
      "currency_id": 0,
      "transaction": "aed3db9ef94953f65e93d56a4e5bcf234d43e27a1b3e7ce0f274cc7ed750d0e2",
      "private_key": "5e92ec09501a5d39e251a151f84b5e2228312c445eb23b4e1de6360e27bad54b",
      "timestamp": 1541203656000,
      "submit_status": 3
    }
  ]
}

# How can I test webhooks?

You can easily test the webhooks by our testing interface. All you need is an API key, a target URL and a hash that is already timestamped, e.g.: 2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e

# Request

POST /v3/webhook/start (opens new window)

# Payload

{
  "hash": "2c5d36be542f8f0e7345d77753a5d7ea61a443ba6a9a86bb060332ad56dba38e",
  "webhook_url": "YOUR_TARGET_URL”
}

Please set the authorization header with your API key.

# Error Handling

For each failed attempt an error counter is incremented. Overall, OriginStamp makes several attempts at regular intervals until the webhook is successfully accepted by the target.

If after several attempts the notification could not be delivered, the event will be aborted.

Should there be longer outages or network issues on the target system, a status request against OriginStamp is advised regarding the webhook status or the state of the hash. The timing should be with some delay after the last blockchain submission.

← Troubleshooting →