Receiving and handling webhook messages

 

With a webhook you can receive notifications when something happens with a hopper. In this tutorial you will learn how to verify your webhook and start receiving and handling webhook messages of the API. In this tutorial we will use the PHP language to create our webhook, but off course you will also be able to create your webhook in any other programming language. Clearly you will need a public server where we can send the webhook messages to, and the public server needs to be protected with a SSL certificate, it needs to be accessible through https. You will also need an app on Cryptohopper, if you haven't created an app yet, please go to Apps and create your first app.

Preparing your webhook

Before we configure and connect your webhook to your app, we will prepare your webhook on your server. Copy the PHP code underneath and place it in the public folder of your server. Let's name it webhook.php.

<?php

$app_secret = 'ENTER_YOUR_APP_SECRET';
$verification_code = 'MY_VERIFICATION_CODE';

$requestBody = file_get_contents('php://input');
$headers = getallheaders();
$headers = array_change_key_case($headers, CASE_UPPER);
$json = json_decode($requestBody, true);

$signature = hash_hmac('sha512', $requestBody, $app_secret);

if($signature == $headers['X-HUB-SIGNATURE']){
	//valid webhook request
	if($json['type'] == 'validate'){
		// validate webhook
		echo $verification_code;
	}elseif($json['type'] == 'messages'){
		// receive messages
		print_r($json['messages'], true);
	}else{
		// unkown type
		echo 'Unkown webhook message type.';
	}
}else{
	//invalid signature
	echo 'Invalid signature.';
}
?>

Make sure to adjust the app secret variable and the verification code variable. The app secret can be found when you edit your app, and the verification code can be anything you want. Just make sure you remember the verification code, because you will need when you want to verify your webhook.

Configure your webhook in your app

Now that you have created a webhook on your server, we can configure your webhook in your app. Go to Apps, select your app and click on the "webhook" tab. Click on "Add webhook" and start entering your webhook URL (with https). Next you can configure which type of messages you wish to receive by selecting subscriptions. Finally you need to enter the verification code which you entered in the PHP code on your server, it needs to match exactly. Click validate and save, your webhook should now show underneath in the list of connected webhooks.

Receiving webhook messages

Because the PHP code in the example is designed to just echo and print the webhook messages, you will not see immediately if your webhook code is working. Therefor we need to make some adjustments to the PHP code to forward the webhook messages to email or for example save messages in a database. The decision is yours, it's up to you what you wish to do with the webhook messages.

To simply forward the webhook messages as notifications to your email, you could use and adjust the PHP code in the following example.

<?php

$app_secret = 'ENTER_YOUR_APP_SECRET';
$verification_code = 'MY_VERIFICATION_CODE';
$send_to_email = 'YOUR_EMAIL_ADDRESS';
$subject_email = 'Webhook message received';

$requestBody = file_get_contents('php://input');
$headers = getallheaders();
$headers = array_change_key_case($headers, CASE_UPPER);
$json = json_decode($requestBody, true);

$signature = hash_hmac('sha512', $requestBody, $app_secret);

if($signature == $headers['X-HUB-SIGNATURE']){
	//valid webhook request
	if($json['type'] == 'validate'){
		// validate webhook
		echo $verification_code;
	}elseif($json['type'] == 'messages'){
		// receive messages
		print_r($json['messages'], true);
        if(!empty($json['messages'])){
        	foreach($json['messages'] as $message){
            	$email_message = 'Message type:<br>'.$message['type'];
            	$email_message .= 'Title:<br>'.$message['title'];
            	$email_message .= '<br><br>';
            	$email_message .= 'Message:<br>'.$message['message'];
                
            	mail($send_to_email, $subject_email, $email_message);
            }
        }
	}else{
		// unkown type
		echo 'Unkown webhook message type.';
	}
}else{
	//invalid signature
	echo 'Invalid signature.';
}
?>

Make sure to edit the variables in the above example to match your needs. If you need more information on the possibilities of webhooks, please check the Webhooks API documentation for more information.