Webhooks

curl -X POST "https://larm.sa/stores/$STORE_ID/v1/webhook-subscriptions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_url":"https://app.example.com/larm/webhooks","event_types":["order.created","order.paid","product.updated"],"payload_version":1}'

{
  "data": {
    "id": "8d1f0c2a-4b3e-4a5f-9c6d-7e8f9a0b1c2d",
    "endpoint_url": "https://app.example.com/larm/webhooks",
    "event_types": ["order.created", "order.paid", "product.updated"],
    "payload_version": 1,
    "state": "active",
    "secret_generation": 1,
    "issued_scopes": ["orders:read", "products:read"]
  },
  "secret": "q3V0bWx…base64url…",
  "meta": { "request_id": "…" }
}

{
  "app_id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
  "data": { "id": "ord_8Kd2", "number": 10482, "status": "processing", "payment_status": "paid", "…": "…" },
  "id": "0b7c2f8e-1d3a-4c5b-9e6f-7a8b9c0d1e2f",
  "installation_generation": 1,
  "installation_id": "c7e4a1f2-6b3d-4e8a-9c05-1d2f3a4b5c6d",
  "occurred_at": "2026-10-15T09:13:02Z",
  "payload_version": 1,
  "resource": { "type": "order", "id": "ord_8Kd2", "version": 3 },
  "store_id": "5b1d7a62-0c4e-4f38-9a51-2e7b3c9d8f10",
  "test": false,
  "type": "order.paid"
}

larm-webhook-v1\n{x-larm-timestamp}\n{x-larm-delivery}\n{x-larm-secret-generation}\n{raw body}

import crypto from 'node:crypto'
import express from 'express'

const key = Buffer.from(process.env.LARM_WEBHOOK_SECRET, 'base64url')   // 32 bytes

function verify(raw, headers) {
  const timestamp = headers['x-larm-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const signed = Buffer.concat([
    Buffer.from(`larm-webhook-v1\n${timestamp}\n${headers['x-larm-delivery']}\n${headers['x-larm-secret-generation']}\n`),
    raw,
  ])
  const expected = crypto.createHmac('sha256', key).update(signed).digest()
  return String(headers['x-larm-signature'] ?? '').split(',').some(part => {
    const [scheme, hex] = part.trim().split('=')
    const given = Buffer.from(hex ?? '', 'hex')
    return scheme === 'v1' && given.length === expected.length && crypto.timingSafeEqual(given, expected)
  })
}

const app = express()
app.post('/larm/webhooks', express.raw({ type: 'application/json', limit: '64kb' }), (req, res) => {
  if (!verify(req.body, req.headers)) return res.sendStatus(401)
  const event = JSON.parse(req.body)
  if (event.id !== req.headers['x-larm-event-id']) return res.sendStatus(401)
  queue.push(event)            // process later
  res.sendStatus(204)          // and acknowledge immediately
})

import base64, hashlib, hmac, json, os, time
from flask import Flask, request, abort

secret = os.environ["LARM_WEBHOOK_SECRET"]
key = base64.urlsafe_b64decode(secret + "=" * (-len(secret) % 4))   # 32 bytes
app = Flask(__name__)

def verify(raw: bytes, headers) -> bool:
    timestamp = headers.get("x-larm-timestamp", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    signed = (
        f"larm-webhook-v1\n{timestamp}\n{headers.get('x-larm-delivery')}\n"
        f"{headers.get('x-larm-secret-generation')}\n"
    ).encode() + raw
    expected = hmac.new(key, signed, hashlib.sha256).hexdigest()
    for part in headers.get("x-larm-signature", "").split(","):
        scheme, _, value = part.strip().partition("=")
        if scheme == "v1" and hmac.compare_digest(value, expected):
            return True
    return False

@app.post("/larm/webhooks")
def webhook():
    raw = request.get_data()
    if not verify(raw, request.headers):
        abort(401)
    event = json.loads(raw)
    enqueue(event)
    return "", 204

<?php
$secret = getenv('LARM_WEBHOOK_SECRET');
$key = base64_decode(strtr($secret, '-_', '+/') . str_repeat('=', (4 - strlen($secret) % 4) % 4));
$raw = file_get_contents('php://input');
$h = fn ($name) => $_SERVER['HTTP_' . strtoupper(str_replace('-', '_', $name))] ?? '';

$timestamp = $h('x-larm-timestamp');
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) { http_response_code(401); exit; }

$signed = "larm-webhook-v1\n{$timestamp}\n" . $h('x-larm-delivery') . "\n" . $h('x-larm-secret-generation') . "\n" . $raw;
$expected = hash_hmac('sha256', $signed, $key);
$valid = false;
foreach (explode(',', $h('x-larm-signature')) as $part) {
    [$scheme, $value] = array_pad(explode('=', trim($part), 2), 2, '');
    if ($scheme === 'v1' && hash_equals($expected, $value)) { $valid = true; }
}
if (!$valid) { http_response_code(401); exit; }

$event = json_decode($raw, true);
enqueue($event);
http_response_code(204);

curl -X POST "https://larm.sa/stores/$STORE_ID/v1/webhook-subscriptions/$SUBSCRIPTION_ID/rotate-secret" \
  -H "Authorization: Bearer $ACCESS_TOKEN"