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).
Webhook Headers
Section titled “Webhook Headers”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. |
Event Catalog
Section titled “Event Catalog”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. |
Sample Payload
Section titled “Sample Payload”{ "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" }}Signature Verification
Section titled “Signature Verification”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...Signature Computation:
Section titled “Signature Computation:”- Extract
t(Unix timestamp) andv1(signature) from the header. - Form the signature payload string by concatenating:
${t}.${raw_request_body}. - Compute the
HMAC-SHA256of that string using your webhook signing secret (whsec_...). - Compare using a constant-time comparison algorithm.
- (Recommended) Reject requests older than 5 minutes (
300seconds) to defend against replay attacks.
Implementation Code Samples
Section titled “Implementation Code Samples”Node.js / Express (TypeScript)
Section titled “Node.js / Express (TypeScript)”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))}Python (FastAPI)
Section titled “Python (FastAPI)”import hmacimport hashlibimport timefrom 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")PHP / Laravel
Section titled “PHP / Laravel”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); }}Delivery Guarantees & Retries
Section titled “Delivery Guarantees & Retries”- Timeout: Akoole expects your endpoint to return a
2xxHTTP response within 10 seconds. - Retry Schedule: If your server returns an error (
4xxor5xx) 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-Idor the payloadidin your database. If you receive a delivery with an ID you have already processed, return200 OKimmediately.