Beginner guide

How to receive a webhook on your server

No prior webhook experience needed. By the end of this page you'll have a working listener, a public URL, and a webhook registered in your Ultraner console.

Prefer to have an AI walk you through it?

What is a webhook?

A webhook is Ultraner reaching out to your server the moment something happens, a payment succeeds, a subscription renews, a transfer completes, instead of you constantly asking "is it done yet?". You give Ultraner a URL once, and from then on Ultraner sends a small HTTP request to that URL every time a matching event occurs. All you need is a URL that's always reachable and a few lines of code to read what arrives.

1. Create a listener

A listener is just a normal web server with one route that accepts POST requests. Pick your language below, this is a complete, runnable file, copy it as a starting point:

Code

const express = require("express");
const crypto = require("crypto");
const app = express();

// Ultraner needs the RAW request body to verify the signature correctly,
// don't use express.json() on this route.
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/ultraner", (req, res) => {
  const signature = req.headers["x-ultraner-signature"];
  const expected = "sha256=" +
    crypto.createHmac("sha256", process.env.ULTRANER_WEBHOOK_SECRET)
          .update(req.body)
          .digest("hex");

  if (signature !== expected) {
    return res.status(401).send("Invalid signature");
  }

  // Respond fast, then handle the event, Ultraner retries if you're slow.
  res.status(200).send("OK");

  const { event, data } = JSON.parse(req.body);
  console.log("Received event:", event, data);
  // TODO: update your database, unlock access, send a receipt, etc.
});

app.listen(3000, () => console.log("Listening on port 3000"));

import hmac
import hashlib
import os
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/ultraner", methods=["POST"])
def ultraner_webhook():
    signature = request.headers.get("X-Ultraner-Signature", "")
    secret = os.environ["ULTRANER_WEBHOOK_SECRET"].encode()
    expected = "sha256=" + hmac.new(secret, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return "Invalid signature", 401

    payload = request.get_json()
    print("Received event:", payload["event"], payload["data"])
    # TODO: update your database, unlock access, send a receipt, etc.

    return "OK", 200

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

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ULTRANER_SIGNATURE'] ?? '';
$secret = getenv('ULTRANER_WEBHOOK_SECRET');
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

http_response_code(200);
echo 'OK';

$event = json_decode($payload, true);
error_log('Received event: ' . $event['event']);
// TODO: update your database, unlock access, send a receipt, etc.

require "sinatra"
require "openssl"
require "json"
require "rack/utils"

post "/webhooks/ultraner" do
  payload = request.body.read
  signature = request.env["HTTP_X_ULTRANER_SIGNATURE"].to_s
  secret = ENV["ULTRANER_WEBHOOK_SECRET"]
  expected = "sha256=" + OpenSSL::HMAC.hexdigest("sha256", secret, payload)

  halt 401, "Invalid signature" unless Rack::Utils.secure_compare(expected, signature)

  status 200
  body "OK"

  data = JSON.parse(payload)
  puts "Received event: #{data['event']}"
  # TODO: update your database, unlock access, send a receipt, etc.
end

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"log"
	"net/http"
	"os"
)

func handler(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	signature := r.Header.Get("X-Ultraner-Signature")
	secret := os.Getenv("ULTRANER_WEBHOOK_SECRET")

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(expected), []byte(signature)) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	w.WriteHeader(http.StatusOK)
	w.Write([]byte("OK"))

	log.Println("Received webhook:", string(body))
	// TODO: update your database, unlock access, send a receipt, etc.
}

func main() {
	http.HandleFunc("/webhooks/ultraner", handler)
	log.Fatal(http.ListenAndServe(":3000", nil))
}

What this file actually does

Accepts a POST request at one URL, e.g. /webhooks/ultraner.
Recomputes the signature from the raw request body and your secret, and compares it to the X-Ultraner-Signature header, this proves the request really came from Ultraner and wasn't tampered with.
Responds 200 immediately, then does the real work, slow responses cause Ultraner to retry and can create duplicate processing.
Reads event (e.g. payment.success) and data from the body to decide what to do.

2. Get a public URL

Ultraner needs to reach your server from the internet, localhost alone won't work.

While developing locally, use a tunnel like ngrok to get a temporary public HTTPS URL for your local server:

Code

ngrok http 3000

# ngrok prints a URL like:
# https://a1b2-c3d4.ngrok-free.app
# Use https://a1b2-c3d4.ngrok-free.app/webhooks/ultraner as your webhook URL below.

In production, just use your real domain, e.g. https://yourapp.com/webhooks/ultraner, as long as it's HTTPS and publicly reachable, no tunnel needed.

3. Register it with Ultraner

Open Console → Webhooks, click New Webhook, paste your URL, and click the events you want (they're grouped by category, no need to type event names). Save, and copy the signing secret shown, it isn't shown again, that's the value your listener above uses as ULTRANER_WEBHOOK_SECRET. Full reference: Webhooks in the API docs.

4. Test it

Use a sandbox uk_test_ API key and trigger a payment with a phone number ending in 700000001 (instant simulated success, no real gateway involved), then watch your server logs, you should see the event arrive within seconds. See sandbox mode for the full fixture list.

That's it, your server can now receive real-time events for payments, recurring subscriptions, disbursements, and more. See every real event type at Webhooks or start from a full working example at a SaaS platform integration.

Stuck? Email support@ultraner.com or ask an AI coding assistant, paste it the full docs as markdown for context.