Webhooks

The easiest way to get product purchase notifications to your services

What are webhooks?

Webhooks are a system used to alter the behavior of your web-based service with a callback.

This is an oversimplified diagram on how webhooks work

Callbacks, as the name suggests, are a system that will be called when a certain event takes place. SellSN integrates this system with newly completed orders so that you can:

• Automatically create their license key/account

• Perform an action of your choice

• And much more!

Webhooks are typically done through a HTTP request to a target URL which is acting as the webhook receiver. In this case, SellSN will distribute webhook requests to your web server which is acting as webhook receiver.

---

Security implications

If you're smart, you may be thinking that there may be some security implications with using webhooks to verify that orders have been completed - and you'd be correct.

If a bad actor decides that he wants to get your product for completely free, they could do that if you are improperly using our webhooks system.

By default, there is nothing stopping a bad actor from forging a fake webhook request to your web server and causing all sorts of unintended behavior from happening - so we devised a system to prevent this from happening.

An example of what a bad actor could do if your webhook system is not configured correctly.

How can I implement them?

If you are not a developer and just want to configure webhooks in your application, follow this help article instead, and get your developer to follow this guide.

Well we made it as easy as pie to implement whilst keeping security tight. Find below some examples on how to accept a webhook correctly in your web application.

C#

// This example is assuming you are using ASP.NET Core with .NET v6.0+
// You can adjust it accordingly to your implementation.

using System.Security.Cryptography;
using System.Text;
using System.IO;

var requestBody = await new StreamReader(HttpContext.Request.Body).ReadToEndAsync(cancellationToken);

if (!Request.Headers.TryGetValue("X-Webhook-Signature", out var recvSignature)) // Get the received signature
		return BadRequest(); // If there is no signature provided, we can rule it out immediately and refuse the request

using var stream = new MemoryStream(Encoding.UTF8.GetBytes(requestBody)); // Create a memory stream for the body
		
var hmac = new HMACSHA256("thisismysecretrighthere"u8.ToArray()); // Load the secret into the HMAC implementation
var hash = await hmac.ComputeHashAsync(stream, cancellationToken); // Generate our own HMAC signature from the body
if (!Convert.ToHexString(hash).Equals(recvSignature.First(), StringComparison.OrdinalIgnoreCase)) // Compare, if fail refuse the request
		return BadRequest("Invalid webhook request");
		
// If you are here, then the request was valid and you can do whatever processing you need

Python

# This example is assuming you use the Flask web framework
# You can adjust this code to fit your own needs if required
# All you need to do is adjust getting the appropriate headers and request body

import hmac, hashlib
from flask import request, jsonify

recv_signature = bytes.fromhex(request.headers["X-Webhook-Signature"]) # Get the received signature as bytes
secret = b'thisismysecretrighthere' # Enter your secret key between the quotes

request_body = request.data  # Get the request body as bytes
signature = hmac.new(secret, request_body, hashlib.sha256).hexdigest() # Generate our own HMAC signature from the body

if not hmac.compare_digest(bytes.fromhex(signature), recv_signature):  # Compare, if fail refuse the request
  print("Webhook request could not be verified as legitimate")
  return jsonify({"message": "We have refused your order on security grounds"}), 403

# If you are here, then the request was valid and you can do whatever processing you need

PHP

<?php
  $request_body = file_get_contents('php://input'); // Get the request body
  $secret = 'thisismysecretrighthere'; // Enter your secret key between the quotes
  $recv_signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE']; // Get the received signature
  $signature = hash_hmac('sha256', $request_body, $secret); // Generate our own HMAC signature from the body
  
   // Compare, if fail refuse the request
    die('Invalid webhook request');
  }
  
  //  If you are here, then the request was valid and you can do whatever processing you need
?>

NodeJS

const crypto = require('crypto'); // Import the crypto lib

const secret = 'thisismysecretrighthere'; // Enter your secret key between the quotes
const headerSignature = req.headers['X-Webhook-Signature']; //  Get the received signature
const payload = req.body; // Get the request body

const signature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex'); // Generate our own HMAC signature from the body


if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(headerSignature, 'utf-8'))) { // Compare, if fail refuse the request
  // Invalid webhook request, return a bad request maybe?
  console.error("Invalid webhook request");
  
  // Make sure you return here because otherwise it will fall down below
}

// If you are here, then the request was valid and you can do whatever processing you need

Security alert! If you improperly or do not implement the webhook verification system, bad actors could exploit your webhook listener to get free stuff from your store!

If you are using a different programming language or the examples are not helpful for you, here are some tips for developing your own integration:

• We are using SHA256 with HMAC, most languages have a cryptography library to perform the required actions

• We send the webhook signature in the X-Webhook-Signature header, it is HEX-encoded.

And step-by-step, you can make your own system:

• Get the request body, your secret and the received webhook signature (the one in the X-Webhook-Signature header), you may need to convert it to a byte array or similar type.

• Now, calculate your own signature by passing your secret and the request body into a HMAC function configured to use SHA256.

• Finally, HEX encode the new hash you created and compare it against the one we sent you in the request.

• Profit!