Overview & Verification

Webhooks allow you to set up a notification system that can be used to receive updates on certain requests made to the Startbutton API.

With webhooks, Startbutton sends updates to your server when the status of your request changes. You will typically listen to these events on your webhook URL - a POST endpoint, the URL needs to parse a JSON request and return a 200 OK.

We send webhooks for the following transaction types:

1. Collections

2. Transfers

3. Conversions

4. Refunds

5. Disputes

Webhook Verification

To ascertain that the request you received on your webhook is legit and not a bad actor, it's recommended that the webhook response is verified.

Events sent from Startbutton carry the following header:

Header	Value
x-startbutton-signature	HMAC SHA512 signature of the event payload signed using your secret key

Verify the header signature before processing the event.

Here is a sample code showing the webhook verification

Node (Express)

var crypto = require('crypto'); 
var secret = process.env.MERCHANT_SECRET_KEY; 
// Using Express 
app.post("/my/webhook/url", function(req, res) { 
    //validate event 
    const hash = crypto.createHmac('sha512', secret).update(JSON.stringify(req.body)).digest('hex'); 
    if (hash == req.headers['x-startbutton-signature']) { 
    // Retrieve the request's body 
    const event = req.body; 
    // Do something with event  
    } 
    res.send(200); 
});

C#

using System; 
using System.Text; 
using System.Security.Cryptography; 
using Microsoft.AspNetCore.Mvc; 
using Microsoft.AspNetCore.Http; 
using Newtonsoft.Json; 

public class WebhookController : ControllerBase 
{ 
    private readonly string secret = Environment.GetEnvironmentVariable("MERCHANT_SECRET_KEY"); 

    [HttpPost("/my/webhook/url")] 
    public IActionResult HandleWebhook([FromBody] WebhookData requestBody) 
    { 
        // Convert the request body to JSON 
        string jsonBody = JsonConvert.SerializeObject(requestBody); 

        // Validate the event 
        string hash = CalculateHash(jsonBody); 

        if (hash == Request.Headers["x-startbutton-signature"]) 
        { 
            // Request is valid, process the event 
            // You can access the JSON data in 'requestBody' 
            // Do something with the event 
        } 

        return Ok(); 
    } 

    private string CalculateHash(string data) 
    { 
        using (var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(secret))) 
        { 
            byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(data)); 
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower(); 
        } 
    } 
    
    
    public class WebhookData 
    { 
        public string @event { get; set; } 
        public WebhookDataObj data { get; set; } 
    } 


    public class WebhookDataObj 
    { 
        public WebhookTransaction transaction { get; set; } 
        public string authorizationCode { get; set; } 
    } 

    public class WebhookTransaction 
    { 
        public string _id { get; set; } 
        public string transType { get; set; } 
        public string status { get; set; } 
        public string merchantId { get; set; } 
        public string transactionReference { get; set; } 
        public string customerEmail { get; set; } 
        public string paymentPartnerId { get; set; } 
        public string paymentCode { get; set; } 
        public string userTransactionReference { get; set; } 
        public bool isRecurrent { get; set; } 
        public string postProcess { get; set; } 
        public string createdAt { get; set; } 
        public string updatedAt { get; set; } 
        public int feeAmount { get; set; } 
        public int amount { get; set; } 
        public string currency { get; set; } 

}
}

Java (SpringBoot)

package com.example.demot; 

import com.fasterxml.jackson.core.JsonProcessingException; 
import com.fasterxml.jackson.databind.ObjectMapper; 
import lombok.Getter; 
import lombok.Setter; 
import org.springframework.beans.factory.annotation.Value; 
import org.springframework.boot.SpringApplication; 
import org.springframework.boot.autoconfigure.SpringBootApplication; 
import org.springframework.http.ResponseEntity; 
import org.springframework.web.bind.annotation.PostMapping; 
import org.springframework.web.bind.annotation.RequestBody; 
import org.springframework.web.bind.annotation.RequestHeader; 
import org.springframework.web.bind.annotation.RestController; 

import javax.crypto.Mac; 
import javax.crypto.spec.SecretKeySpec; 
import java.security.InvalidKeyException; 
import java.security.NoSuchAlgorithmException; 
import java.util.Formatter; 


@RestController 
class WebhookController { 

    private final String secret = System.getenv("MERCHANT_SECRET_KEY"); 
    private static final String HMAC_SHA512 = "HmacSHA512"; 

    @PostMapping("/webhook") 
    public ResponseEntity<?> handleWebhook(@RequestHeader("x-startbutton-signature") String signature, 
                                           @RequestBody ReqObject requestBody) throws JsonProcessingException, NoSuchAlgorithmException, InvalidKeyException { 

        String requestBodyString = new ObjectMapper().writeValueAsString(requestBody); 
        String returnedHash = calculateHMAC(requestBodyString, secret); 
        return returnedHash.equals(signature) ? ResponseEntity.ok().build() : ResponseEntity.badRequest().build(); 
    } 

    public static String calculateHMAC(String data, String key) throws NoSuchAlgorithmException, InvalidKeyException { 
        SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(), HMAC_SHA512); 
        Mac mac = Mac.getInstance(HMAC_SHA512); 
        mac.init(secretKeySpec); 
        byte[] bytes = mac.doFinal(data.getBytes()); 
        Formatter formatter = new Formatter(); 
        for (byte b : bytes) { 
            formatter.format("%02x", b); 
        } 
        return formatter.toString(); 
    } 

} 

@Getter 
@Setter 
class ReqObject { 
    private String event; 
    private Data data; 
} 

@Getter 
@Setter 
class Data { 
    private Transaction transaction; 
    private Object authorizationCode; 
} 

@Getter 
@Setter 
class Transaction { 
    private String _id; 
    private String transType; 
    private String status; 
    private String merchantId; 
    private String transactionReference; 
    private String customerEmail; 
    private String paymentCode; 
    private String userTransactionReference; 
    private Boolean isRecurrent; 
    private String postProcess; 
    private String createdAt; 
    private String updatedAt; 
    private Integer feeAmount; 
    private Integer amount; 
    private String currency; 
} 

Python (Flask)

import os 
import json 
import hashlib 
from flask import Flask, request, jsonify 

app = Flask(__name__) 
secret = os.environ.get("MERCHANT_SECRET_KEY") 

@app.route("/my/webhook/url", methods=["POST"]) 
def handle_webhook(): 
    # Get the request data as a JSON string 
    request_data = request.data.decode("utf-8") 

    # Validate the event 
    hash_value = calculate_hash(request_data) 

    if hash_value == request.headers.get("x-startbutton-signature"): 
        # Request is valid, process the event 
        event_data = json.loads(request_data) 
        # Do something with the event data 

    return "", 200 

def calculate_hash(data): 
    # Calculate HMAC-SHA512 hash of the data 
    hmac = hashlib.new("sha512", secret.encode("utf-8")) 
    hmac.update(data.encode("utf-8")) 
    return hmac.hexdigest() 

if __name__ == "__main__": 
    app.run()

Ruby (Ruby on Rails)

class WebhookController < ApplicationController 
  protect_from_forgery with: :null_session 

  def handle_webhook 
    secret = ENV['MERCHANT_SECRET_KEY'] 
    request_body = request.body.read 
    signature = request.headers['x-startbutton-signature'] 

    if is_valid_signature?(secret, request_body, signature) 
      # Request is valid, process the event 
      event_data = JSON.parse(request_body) 
      # Do something with the event data 
    end 

    head :ok 
  end 

  private 

  def is_valid_signature?(secret, data, signature) 
    calculated_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha512'), secret, data) 
    calculated_signature == signature 
  end 
end

PHP (laravel)

<?php 

namespace App\Http\Controllers; 

use Illuminate\Http\Request; 
use Illuminate\Http\Response; 

class WebhookController extends Controller 
{ 
    public function handleWebhook(Request $request) 
    { 
        $secret = env('MERCHANT_SECRET_KEY'); 
        $requestBody = $request->getContent(); 
        $signature = $request->header('x-startbutton-signature'); 

        if ($this->isValidSignature($secret, $requestBody, $signature)) { 
            // Request is valid, process the event 
            $eventData = json_decode($requestBody, true); 
            // Do something with the event data 
        } 

        return response()->json([], Response::HTTP_OK); 
    } 

    private function isValidSignature($secret, $data, $signature) 
    { 
        $calculatedSignature = hash_hmac('sha512', $data, $secret); 
        return hash_equals($calculatedSignature, $signature); 
    } 
}

Final Notes

To wrap up your webhook implementation, here is the ideal flow your webhook endpoint should follow

1. Verify request is from us using secret key and payload sent

2. Re-query Transaction Status Query

3. Send 200 status back immediately and handle complex logic on your end

4. Ensure webhook responses are idempotent. Save the response and ensure value isn't give twice since you can get multiple calls for a transaction.