Callbacks

Callbacks are POST (as JSON encoded request body) requests made by Uniwire to URL endpoint specified in Profile that was used for related invoice creation.

Callback expects HTTP 200 OK success status response code (any 20X status will work too). For any other status code or timeout it will try to reach endpoint again with exponential time increase between retries. If after 72 hours endpoint will be still unreachable callback sender will stop trying.

You can view history of callbacks in Uniwire app under every instance that have callbacks.

Callbacks Verification

To verify callback and make sure it really comes from Uniwire you must use Callback Token which you can find in Uniwire app under Settings > API Keys.

Always verify if signature provided in callback POST data matches the one you generate on your own by signing callback_id value with callback_token using following hashing algorithm:

python

import hashlib
import hmac
import json

# You will find your callback token under Settings
CALLBACK_TOKEN = 'your_callback_token'


# You can reuse same method used in API auth signature generation
def encode_hmac(key, msg, digestmod=hashlib.sha256):
    return hmac.new(key.encode(), msg=msg, digestmod=digestmod).hexdigest()


# Decode request json body
payload = json.loads(request.body)

# Get signature and callback_id fields from provided data
signature = payload['signature']
callback_id = payload['callback_id']

# Compare signatures
is_valid = signature == encode_hmac(CALLBACK_TOKEN, callback_id.encode())
assert is_valid, 'Failed to verify Uniwire callback signature.'

# Debug callback data
print(json.dumps(payload, indent=2))

javascript

const Base64 = require('js-base64').Base64;
const crypto = require('crypto');

// You will find your callback token under Settings
const CALLBACK_TOKEN = 'your_callback_token';

// You can reuse same method used in API auth signature generation
function encode_hmac(key, msg) {
  return crypto.createHmac('sha256', key).update(msg).digest('hex');
}

// Decode request json body
var payload = JSON.parse(request.body);

// Get signature and callback_id fields from provided data
const signature = payload['signature'];
const callback_id = payload['callback_id'];

// Compare signatures
const is_valid = signature === encode_hmac(CALLBACK_TOKEN, callback_id);
if (!is_valid) {
  throw new Error('Failed to verify Uniwire callback signature.');
}

// Debug callback data
console.log(payload);

signature = hex(HMAC_SHA256(<callback_id>, key=<callback_token>))

Callbacks Response

All callbacks have these fields in common:

Key	Meaning
callback_id	Unique callback ID. If callback fails to reach endpoint, it will retry with the same ID.
callback_status	Callback status identifying specific event.
signature	Uniwire signature for verification.

For event specific response documentation see Callback section under specific endpoint.