Webhook Signature

How Teapplix signs an outbound webhook

All Teapplix HTTP webhooks comes signed with SHA-256 signature. Together with APIToken, each account has Signature key (can be found at Setup-API menu).

The common signature calculation algorithm is simple: take data submitted and calculate HMAC hash using SHA-256 hashing algorithm with account Signature Key. Then encode with base64 and attach as HTTP header named X-HMAC-SHA256.

How should the recipient of the webhook check the signature

To check the signature:

1. First know your Signature Key (Setup - API menu).
2. When data is received, read header X-HMAC-SHA256. This is request signature.
3. Calculate HMAC hash of request body using SHA256 algorithm.
4. BASE64 encode value from step 3. This is calculated signature.
5. Compare values from step 2 and step 5. If they are equal - request is correct.

Note: Teapplix send data in UTF-8 encoding. Please make sure you don't do any encoding transformation prior to calculating signature.

Code example

This is example of PHP script accepting incoming webhooks.

<?php
$signatureKey = 'a12345';
$headers = apache_request_headers();
$content = @file_get_contents('php://input');
$receivedSignature = isset($headers['X-HMAC-SHA256']) ? $headers['X-HMAC-SHA256'] : '';
$calculatedSignature = base64_encode(hash_hmac('sha256', $content, $signatureKey, true));
if($receivedSignature == $calculatedSignature) {
//correctly signed webhook, accept
} else {
//incorrectly signed webhook, decline
}