Using webhooks with Selz

You can use webhooks to be notified about events that happen in your Selz account

To setup a webhook, head to ‘Developer’ in the ‘Settings’ within your Selz dashboard and then:

  1. From the first drop-down, select the ‘Event’ you want a webhook for from the dropdown
  2. Under ‘Callback URL’, enter the URL you want the payload sent to
  3. Click ‘Add webhook’ and your webhook should now appear in the list

You also have the ability to test your webhook, to make sure the information you want is being sent to the correct URL. To do this click the send test notification link. You’ll then need to check that your callback URL is receiving the payload. Here’s an example of a webhook payload for when an item is ordered:

{
   "webhook_id":"5840c0bacca9180d0866ba2c",
   "event_type":"order_payment_succeeded",
   "timestamp":"2016-12-02T00:30:50",
   "token":"WEDAuucHsQQ0D+81S4SizL1MstKQVkHeVTFjHqa7sTnnVVYh",
   "data":{
      "id":"5840c0bae707b10aa48d55c5",
      "reference_id":"XZHQ59WA",
      "customer":{
         "id":"5840c0bae707b10aa48d55c6",
         "created_time":"0001-01-01T00:00:00",
         "first_name":"John",
         "last_name":"Doe",
         "email":"support@selz.com",
         "company":"Doe & Co",
         "delivery_address":{
            "line1":"1 Infinite Loop",
            "line2":null,
            "city":"Cupertino",
            "post_code":"95014",
            "state_code":"CA",
            "country_code":"US"
         },
         "billing_address":{
            "line1":"1 Infinite Loop",
            "line2":null,
            "city":"Cupertino",
            "post_code":"95014",
            "state_code":"CA",
            "country_code":"US"
         }
      },
      "items":[
         {
            "product_id":"5840c0bae707b10aa48d55c7",
            "product_title":"Example",
            "product_variant_title":null,
            "discount_code":null,
            "quantity":1,
            "unit_price":"10.00",
            "currency":"USD"
         }
      ],
      "currency":"USD",
      "total_price":"20.00",
      "total_shipping":"5.00",
      "total_tax":"5.00",
      "price_includes_tax":false,
      "status":0,
      "created_time":"2016-12-02T00:30:50.0985914Z",
      "tracking_id":"123abc",
      "custom_fields":null
   }
}

In order to test your webhooks you can also use requestb.in for testing.

Securing Webhooks

Webhooks can be verified by calculating a digital signature.

Each Webhook request includes a HTTP_X_SELZ_SIGNATURE header along with the data sent in the request.
To verify that the request came from Selz, compute the HMAC digest according to the following algorithm and compare it to the value in the HTTP_X_SELZ_SIGNATURE header.
If they match, you can be sure that the Webhook was sent from Selz and the data has not been compromised.

PHP Example

<?php
$json = json_decode(file_get_contents('php://input'), TRUE);
$message = $json["timestamp"].$json["token"];
 
if(!ValidateSignature($message)){
    header("HTTP/1.1 400 BAD REQUEST");
    die();
}
 
// Do something with webhook payload
$orderId = $json["data"]["id"];
 
header("HTTP/1.1 200 OK");
die();
 
function CreateSignature($message) {
    $key = 'your_webhook_verification_key';
 
    $aMessage = iconv(iconv_get_encoding("internal_encoding"), "ASCII", $message);
    $aKey = iconv(iconv_get_encoding("internal_encoding"), "ASCII", $key);
 
    $sig = hash_hmac('sha256', $aMessage, $aKey, true);
    return base64_encode($sig);
}
 
function ValidateSignature($message){
    $signature = $_SERVER["HTTP_X_SELZ_SIGNATURE"];
    $signatureToCompare = CreateSignature($message);
 
    return ($signature == $signatureToCompare);
}
?>

Node.js Example

var crypto = require('crypto');
 
app.post('/webhook', function (req, res) {
    // https://github.com/visionmedia/express/wiki/Migrating-from-3.x-to-4.x
    // express 3.x: app.use(express.bodyParser());
    // express 4.x: app.use(bodyParser());
    var json = req.body;
    res.send(200);
        
    var signature = req.headers['x-selz-signature'];
    var message = json["timestamp"] + json["token"];
        
 
    if (validateSignature(message, signature)) {
        console.log('OK');
    } else {
        console.log('ERROR');    
    }
});
 
 
function createSignature(message) {
    var key = 'your_webhook_verification_key';
        
    return crypto.createHmac('sha256', key).update(message, 'ascii').digest('base64');
}
    
function validateSignature(message, signature) {
    var signatureToCompare = createSignature(message);
        
    return (signature == signatureToCompare);
}

Was this helpful?

8 2