Skip to content

Webhooks & Signature Verification

Outbound Webhooks allow your server to receive real-time push notifications from Akoole whenever important business events occur (such as a POS sale completion, a new customer order, an inventory adjustment, or a low-stock alert).


Every HTTP POST request dispatched to your webhook endpoint contains the following headers:

Header Description
X-Akoole-Signature The cryptographic HMAC-SHA256 signature string: t={timestamp},v1={hex_signature}.
X-Akoole-Event The event name (e.g. sale.completed, inventory.low_stock).
X-Akoole-Delivery-Id Unique ULID identifying this delivery attempt. Use this to ensure idempotency.
User-Agent Always Akoole-Webhooks/1.0.
Content-Type Always application/json.

You can subscribe to specific events or listen to all events using *:

Event Slug Domain Description
sale.completed Sales Dispatched when a sale is finalized at POS or checkout.
sale.refunded Sales Dispatched when a sale is refunded in whole or part.
order.created Orders Dispatched when an online storefront order is placed.
order.status_updated Orders Dispatched when an order transitions (e.g. processing, fulfilled, cancelled).
inventory.adjusted Inventory Dispatched when a staff member or transfer modifies stock count.
inventory.low_stock Inventory Dispatched when product stock drops below the configured reorder threshold.
product.created Catalogue Dispatched when a new product is added.
product.updated Catalogue Dispatched when product details, variants, or pricing change.
product.deleted Catalogue Dispatched when a product is deleted.
customer.created Customers Dispatched when a new customer profile is registered.
customer.updated Customers Dispatched when customer phone, name, or metadata changes.
ping System Sample test ping dispatched manually from the dashboard.

{
"id": "01J9X1234567890ABCDEF12345",
"event": "sale.completed",
"created_at": "2026-10-08T12:00:00Z",
"organisation_uuid": "01HZX8M9N1ABCD23EF45GH67JK",
"data": {
"sale_uuid": "01J9X12ABCD34EF56GH78JK90",
"total_kobo": 1250000,
"currency": "NGN",
"items_count": 3,
"payment_method": "card",
"branch_uuid": "01HZX99BRANCH00000000000"
}
}

To guarantee that incoming requests originate from Akoole and have not been altered in transit, you must verify the X-Akoole-Signature header.

The signature header contains a timestamp and a hex-encoded SHA256 HMAC:

X-Akoole-Signature: t=1760000000,v1=5d41402abc4b2a76b9719d911017c592...
  1. Extract t (Unix timestamp) and v1 (signature) from the header.
  2. Form the signature payload string by concatenating: ${t}.${raw_request_body}.
  3. Compute the HMAC-SHA256 of that string using your webhook signing secret (whsec_...).
  4. Compare using a constant-time comparison algorithm.
  5. (Recommended) Reject requests older than 5 minutes (300 seconds) to defend against replay attacks.

import crypto from 'node:crypto'
import type { Request, Response } from 'express'
export function verifyWebhook(req: Request, res: Response, secret: string): boolean {
const header = req.headers['x-akoole-signature']
if (!header || typeof header !== 'string') return false
// 1. Parse t and v1
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const timestamp = parts.t
const signature = parts.v1
if (!timestamp || !signature) return false
// 2. Prevent replay attacks (5 minute threshold)
const tolerance = 300
const now = Math.floor(Date.now() / 1000)
if (Math.abs(now - Number(timestamp)) > tolerance) return false
// 3. Compute expected signature using raw request body buffer
const rawBody = (req as any).rawBody || JSON.stringify(req.body)
const payloadToSign = `${timestamp}.${rawBody}`
const expected = crypto.createHmac('sha256', secret).update(payloadToSign).digest('hex')
// 4. Constant-time comparison
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}
import hmac
import hashlib
import time
from fastapi import Request, HTTPException
def verify_akoole_webhook(raw_body: bytes, signature_header: str, secret: str):
parts = dict(item.split("=") for item in signature_header.split(","))
timestamp = parts.get("t")
signature = parts.get("v1")
if not timestamp or not signature:
raise HTTPException(status_code=400, detail="Invalid signature header")
# 5 minute tolerance
if abs(time.time() - int(timestamp)) > 300:
raise HTTPException(status_code=400, detail="Webhook signature timestamp expired")
payload = f"{timestamp}.".encode("utf-8") + raw_body
expected = hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
raise HTTPException(status_code=403, detail="Signature mismatch")
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\HttpException;
class VerifyAkooleWebhook
{
public function handle(Request $request, Closure $next)
{
$header = $request->header('X-Akoole-Signature');
if (! $header) {
throw new HttpException(400, 'Missing signature header');
}
parse_str(str_replace(',', '&', $header), $parts);
$timestamp = $parts['t'] ?? null;
$signature = $parts['v1'] ?? null;
if (! $timestamp || ! $signature) {
throw new HttpException(400, 'Malformed signature header');
}
if (abs(time() - (int) $timestamp) > 300) {
throw new HttpException(400, 'Timestamp expired');
}
$secret = config('services.akoole.webhook_secret');
$payload = "{$timestamp}." . $request->getContent();
$expected = hash_hmac('sha256', $payload, $secret);
if (! hash_equals($expected, $signature)) {
throw new HttpException(403, 'Invalid signature');
}
return $next($request);
}
}

  • Timeout: Akoole expects your endpoint to return a 2xx HTTP response within 10 seconds.
  • Retry Schedule: If your server returns an error (4xx or 5xx) or times out, the delivery is retried up to 5 times using exponential backoff:
    • Attempt 1: Immediate
    • Attempt 2: ~1 minute
    • Attempt 3: ~5 minutes
    • Attempt 4: ~15 minutes
    • Attempt 5: ~1 hour
  • Automatic Deactivation: To protect your server from being flooded during an outage, an endpoint will be automatically marked Inactive after 10 consecutive failures. You can re-enable it at any time in the dashboard.
  • Idempotency: Always store the X-Akoole-Delivery-Id or the payload id in your database. If you receive a delivery with an ID you have already processed, return 200 OK immediately.