You can start receiving event notifications in your app using the steps below:
- Identify the events you want to monitor and the event payloads to parse.
- Create a webhook endpoint as an HTTP endpoint (URL) on your local server.
- Handle requests from Smartpay by parsing each event object and returning 200 response status codes.
- Register your publicly accessible HTTPS URL with Smartpay using the create a webhook endpoint API endpoint .
- Secure your webhooks (recommended).
- Deploy your webhook endpoint so it is a publicly accessible HTTPS URL.
- Test that your webhook endpoint is working properly.
1. Identify the events you want to monitor
Take a look at the supported event types to decide which events you are interested in subscribing to. Check the event object and sample events to see the structure of the objects you need to parse.
2. Create a webhook endpoint
Creating a webhook endpoint is no different from creating any other page on your website. It’s an HTTPS endpoint on your server with a URL. If you’re still developing your endpoint on your local machine, it can be HTTP. On production, it must be HTTPS. You can use one endpoint to handle several different event types at once, or set up individual endpoints for specific events.
3. Handle requests from Smartpay
Your endpoint must be configured to read event objects for the type of event notifications you want to receive. Smartpay sends events to your webhook endpoint as part of a POST request with a JSON payload.
Check event objects
Each event is structured as an event object with an id, type and related Smartpay resource nested under data(the structure of data depends on the event type, as it is the object the event relates to). For more details see the event object. Your endpoint must check the event type and parse the payload of each event.
{
"id": "evt_test_yETRfprzCxFsSJaJZPIENt",
"object": "event",
"createdAt": 1664522079584,
"test": true,
"eventData": {
"type": "order.authorized",
"version": "2022-02-18",
"data": {...}
}
}
Return a 200 response
Your endpoint should quickly return a successful status code (200) prior to any complex logic that could cause a timeout.
The examples below verify the webhook signature (see step 5) and return a 200 HTTP status code. You can find the example code on GitHub as well.
package main
import (
"bytes"
"encoding/json"
"log"
"io/ioutil"
"net/http"
"github.com/smartpay-co/sdk-go"
)
func webhook(w http.ResponseWriter, r *http.Request) {
signature := r.Header.Get("Smartpay-Signature")
calculatedSignature := r.Header.Get("Calculated-Signature")
if signature != calculatedSignature {
log.Println("Signature verification failed.", signature, calculatedSignature)
w.WriteHeader(http.StatusBadRequest)
return
}
var bodyBytes []byte
var err error
if r.Body != nil {
bodyBytes, err = ioutil.ReadAll(r.Body)
if err != nil {
log.Printf("Body reading error: %v", err)
return
}
defer r.Body.Close()
}
log.Printf("Headers: %+v\n", r.Header)
if len(bodyBytes) > 0 {
var prettyJSON bytes.Buffer
if err = json.Indent(&prettyJSON, bodyBytes, "", "\t"); err != nil {
log.Printf("JSON parse error: %v", err)
return
}
log.Println(string(prettyJSON.Bytes()))
} else {
log.Printf("Body: No Body Supplied\n")
}
w.Write([]byte("OK"))
}
func main() {
mux := http.NewServeMux()
webhookHandler := http.HandlerFunc(webhook)
mux.Handle("/", smartpay.CalculateWebhookSignatureMiddleware("YOUR_SIGNING_KEY", webhookHandler))
log.Print("Listening on :3000...")
err := http.ListenAndServe("0.0.0.0:3000", mux)
log.Fatal(err)
}
const crypto = require("crypto");
const express = require("express");
const createError = require("http-errors");
const Smartpay = require("@smartpay/sdk-node").default; // The Nodejs SDK
const app = express();
const secret = "YOUR_SIGNING_KEY";
const log = new Map();
app.use(
express.json({
verify: Smartpay.expressWebhookMiddleware(secret),
})
);
app.post("/webhooks", async (req, res, next) => {
const event = req.body;
const signature = req.headers["smartpay-signature"];
const calculatedSignature = req.headers["calculated-signature"];
console.log(req.headers);
console.log(event);
console.log(calculatedSignature);
if (signature === calculatedSignature) {
const key = req.headers["smartpay-event-id"];
const existing = log.get(key) || {
count: 0,
};
console.log(`key: ${key} count: ${existing.count}`);
if (existing && existing.count >= 2) {
log.delete(key);
res.send("");
return;
}
log.set(key, { count: existing.count + 1 });
}
next(createError.BadRequest());
});
app.listen(3000, "0.0.0.0", () =>
console.log("Node server listening on port 3000!")
);
<?php
require __DIR__ . '/./vendor/autoload.php';
use Tuupola\Base62;
$base62 = new Base62(["characters" => 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789']);
$secret = 'YOUR_SIGNING_KEY';
$app = new \Slim\App;
$app->map(['get', 'post'], '/', function ($request, $response, $args) use (&$base62, &$secret) {
$fileName = trim($request->getUri()->getBasePath(), '/');
if ($fileName == 'webhooks') {
$headers = $request->getHeaders();
$smartpaySignature = $request->getHeader('Smartpay-Signature')[0];
$smartpaySignatureTimestamp = $request->getHeader('Smartpay-Signature-Timestamp')[0];
if ($smartpaySignature && $smartpaySignatureTimestamp) {
$body = $request->getBody();
$parsedBody = $request->getParsedBody();
$calculatedSignature = hash_hmac('sha256', $smartpaySignatureTimestamp . "." . $body, $base62->decode($secret));
print_r($calculatedSignature);
print_r($headers);
print_r($parsedBody);
if ($smartpaySignature == $calculatedSignature) {
return $response;
}
}
return $response->withStatus(400);
} else {
return $response->withStatus(404);
}
});
$app->run();
import os
from flask import Flask, request
from smartpay import Smartpay
SIGNING_SECRET = 'YOUR_SIGNING_KEY'
SECRET_KEY = os.environ.get('SECRET_KEY', '<YOUR_SECRET_KEY>')
PUBLIC_KEY = os.environ.get('PUBLIC_KEY', '<YOUR_PUBLIC_KEY>')
smartpay = Smartpay(SECRET_KEY, public_key=PUBLIC_KEY)
app = Flask(__name__, static_url_path='')
root = '../client/build'
@app.route("/webhooks", methods=['POST'])
def webhooks():
signature = request.headers['smartpay-signature']
verified = smartpay.verify_webhook_signature(data=request.get_data(), secret=SIGNING_SECRET, signature=signature)
if verified:
print("processing webhook event")
return ''
return '', 400
require 'sinatra'
require 'base_x'
set :port, 3000
secret = 'YOUR_SIGNING_KEY'
helpers do
def request_headers
env.inject({}){|acc, (k,v)| acc[$1.downcase] = v if k =~ /^http_(.*)/i; acc}
end
end
post '/webhooks' do
content_type :json
signature = request_headers["smartpay_signature"]
signature_timestamp = request_headers["smartpay_signature_timestamp"]
raw_body = request.body.read
body = JSON.parse raw_body
p BaseX::Base62ULD.decode(secret).bytes
hmac = OpenSSL::HMAC.new(BaseX::Base62ULD.decode(secret), OpenSSL::Digest::SHA256.new)
hmac.update signature_timestamp
hmac.update '.'
hmac.update raw_body
calculated_signature = hmac.hexdigest
p request_headers
p body
p calculated_signature
if signature == calculated_signature
return '', 200
end
return '', 400
rescue => err
if err.respond_to?(:response)
err.response.body
else
raise err
end
end
Built-in retries
Smartpay webhooks have built-in retry for 3xx, 4xx, or 5xx response status codes. If you respond to a webhook request with anything other than 200, Smartpay will keep retrying the request with an exponential backoff.
4. Register your webhook endpoint
Register your newly created webhook endpoint with Smartpay to receive the events you want to subscribe to. You can do this by using the create a webhook API endpoint.
5. Secure your webhooks (recommended)
Use webhook signatures to verify that Smartpay generated a webhook request and that it didn’t come from a server acting like Smartpay.
Smartpay signs the webhook events it sends to your endpoints by including a signature in each event’s Smartpay-Signature header. This allows you to verify that the events were sent by Smartpay and not by a third party. You can verify signatures either using our SDKs, or manually using your own solution.
Before you can verify signatures, you need to retrieve your endpoint’s signingSecret. Smartpay generates a unique signingSecret for each endpoint and returns it to you when you register your webhook endpoint (see step 4) or retrieve a previously registered webhook endpoint.