Purpose

To ensure the durability of the proofs you create on the Woleet platform, it is strongly recommended to download and keep your proof receipts safe as soon as they become available. To that purpose, the platform can inform you about the progress of the anchoring process by calling back URLs of your choice.

Usage

The callback URL must be specified at anchor creation time using the callbackURL property.
The Woleet platform performs a POST request on this URL whenever the status of the anchor change. The anchor is provided as a JSON object in the request body.

The status of the anchor will take the following values (in sequence):

• NEW: proof waiting to be sent to the blockchain (the proof receipt is not yet available for download)
• SENT: proof sent to the blockchain and confirmed 1 time (the proof receipt is available for download)
• CONFIRMED: proof confirmed at least 6 times by the blockchain (the proof receipt is available for download)

To sum up, if the status of an anchor provided by a callback is SENT or CONFIRMED, you can download the associated proof receipt by using the Get the proof receipt of an anchor (Chainpoint proof format). endpoint.

Retry policy

If the POST request of the callback URL fails by returning a status code other than 2xx, or is not reachable, the Woleet platform will try again later.

The retry policy is the following:

• the time between 2 callbacks doubles at each retry
• callback will be definitively canceled after 14 days
• the amount of retries within 14 days is approximately 40 (after 1mn, 2mn, 4mn, etc.)

Also keep in mind that if the state of an anchor changes while the previous state could not be notified, only the last state of the anchor will be notified.

Verifying callback authenticity

Woleet can sign it's callbacks with a HMAC-SHA1 function.
To enable this feature, you must go on Woleet ProofDesk (Account settings -> API) and generate a secret that will be used to sign the callback body.

The signature will be passed to your service in the x-woleet-signature header.

Here is some sample code you can use to verify this signature:

const crypto = require('crypto')
const secret = ... // your signing secret
const body = ... // get the callback's body 
const signature = ... // get the callback's signature

// Generate the signature
const hash = crypto.createHmac('sha1', secret).update(body).digest('base64')

// Checks that signatures match
if (hash !== signature) {
  
	// Signautre is NOT valid...
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

String secret = ... // your signing secret
SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(), "HmacSHA1"); 
String body = // get the callback's body 
String signature = // get the callback's signature

// Generate the signature
Mac mac = Mac.getInstance("HmacSHA1"); 
mac.init(keySpec);  
byte[] hash = mac.doFinal(body.getBytes()); 

// Checks that signatures match
if (!Base64.encode(hash).equals(signature)) {
  
	// Signature is NOT valid...
}