GuidesAPI ReferenceChangelogDiscussions
Woleet.io

Using callback URLs

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 (the proof receipt is available for download, but not yet for verification)
  • CONFIRMED: proof confirmed at least 6 times by the blockchain (the proof receipt is available for download and verification)

To sum up, the status of an anchor provided to a callback can be NEW, SENT or CONFIRMED.
You can download the associated proof receipt by using the Get receipt endpoint as soon as the status is SENT, and you can verify it by using the Verify receipt endpoint as soon as the status is CONFIRMED.

Retry policy

If the POST request on the callback URL fails for any reason (status code other than 2xx, host not reachable, TLS certificate invalid or untrusted) the Woleet platform will retry the call later.

The retry policy is the following:

  • the time between retries increases progressively (it is equal to the number of retries power 2 minutes, like 1mn, 4mn, 9mn, 16mn etc.)
  • callback will be definitively canceled after 14 days
  • the amount of retries within 14 days is approximately 40

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 the body of its callbacks using a HMAC-SHA1 function.

To enable this feature, you must go on Woleet ProofDesk (Account settings -> API) and generate an API callback secret that will be used to sign the body of the callback.

The signature will be passed to your service in the x-woleet-signature header of the HTTP request as a Base64 value.

Here is some sample code (JavaScript and Java) 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...
}