Webhooks & Events

Storno.ro delivers real-time updates through three complementary channels: outbound HTTP webhooks for server-to-server integrations, WebSocket connections (Centrifugo) for live UI updates, and in-app notifications for user-facing alerts.

Outbound Webhooks

Outbound webhooks send HTTP POST requests to your server whenever business events occur. Use them to integrate Storno.ro with ERPs, accounting tools, Slack, or any system that accepts HTTP callbacks.

How it works

1. You create a webhook endpoint with a destination URL and the events you want to receive
2. Storno.ro generates an HMAC-SHA256 signing secret (shown only once — store it securely)
3. When a subscribed event occurs, Storno.ro sends a signed POST request to your URL
4. Your server verifies the signature and processes the payload
5. If delivery fails, Storno.ro retries up to 3 times with exponential backoff

Webhook payload format

Every webhook delivery sends a JSON payload with this structure:

{
  "id": "0192b3a4-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
  "event": "invoice.validated",
  "created_at": "2026-02-19T10:30:00+00:00",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "number": "UEP2026000002",
    "status": "validated",
    "direction": "outgoing",
    "total": "30940.00",
    "currency": "RON"
  }
}

HTTP headers

Each delivery includes these headers:

Verifying signatures

Always verify the X-Webhook-Signature header to ensure the request came from Storno.ro. Compute the HMAC-SHA256 of the raw request body using your signing secret and compare:

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Express middleware example
app.post('/webhooks/storno', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhook(req.rawBody, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.rawBody);
  console.log(`Received ${event.event}:`, event.data);

  res.status(200).send('OK');
});

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = getenv('WEBHOOK_SECRET');

$expected = hash_hmac('sha256', $payload, $secret);

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

$event = json_decode($payload, true);
// Process $event['event'] and $event['data']

http_response_code(200);

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry policy

If your endpoint returns a non-2xx status code or the connection fails, Storno.ro retries with exponential backoff:

After 3 failed attempts the delivery is marked as failed and no further retries are attempted. You can monitor delivery status and errors through the delivery log endpoints.

Best practices for your endpoint:

• Return 200 OK as quickly as possible — process the payload asynchronously
• Respond within 10 seconds (the request times out after that)
• Handle duplicate deliveries idempotently using the id field
• If you return a 2xx status, the delivery is considered successful

Delivery statuses

Event Types

Storno.ro supports 15 event types organized into 5 categories. Retrieve the full list from the API via GET /api/v1/webhooks/events.

Invoice events

Company events

Sync events

Payment events

Provider Authentication Events

Webhook Management

Creating a webhook

curl -X POST https://api.storno.ro/api/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "X-Company: {company_uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks",
    "events": ["invoice.created", "invoice.validated", "payment.received"],
    "description": "ERP integration"
  }'

Testing a webhook

Send a test delivery to verify your endpoint is reachable:

curl -X POST https://api.storno.ro/api/v1/webhooks/{uuid}/test \
  -H "Authorization: Bearer {token}" \
  -H "X-Company: {company_uuid}"

The test sends a webhook.test event synchronously and returns the HTTP result immediately:

{
  "success": true,
  "statusCode": 200,
  "durationMs": 145,
  "error": null
}

Viewing delivery history

curl https://api.storno.ro/api/v1/webhooks/{uuid}/deliveries?page=1&limit=20 \
  -H "Authorization: Bearer {token}" \
  -H "X-Company: {company_uuid}"

Each delivery record includes the event type, HTTP status code, response time, attempt number, and any error message. Use the delivery detail endpoint to inspect the full request payload and response body.

Permissions

API endpoints

Real-Time Updates (Centrifugo)

For live UI updates (browser and mobile), Storno.ro uses Centrifugo WebSocket connections. This is separate from outbound webhooks and intended for front-end applications.

Connecting

1. Obtain a connection token:

curl -X POST https://api.storno.ro/api/v1/centrifugo/connection-token \
  -H "Authorization: Bearer {token}"

2. Connect to the Centrifugo WebSocket server with the returned token

3. Subscribe to channels:

curl -X POST https://api.storno.ro/api/v1/centrifugo/subscription-token \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "user:{user_id}"
  }'

WebSocket event types

Events are published to user-specific and company-specific channels:

Notifications

Storno.ro sends user-facing notifications through multiple channels.

Channels

Notification types

Managing preferences

Users can control which notifications they receive on which channels:

# Get current preferences
curl https://api.storno.ro/api/v1/notification-preferences \
  -H "Authorization: Bearer {token}"

# Update preferences
curl -X PUT https://api.storno.ro/api/v1/notification-preferences \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "invoiceValidated": { "email": true, "inApp": true, "push": false },
      "invoiceRejected": { "email": true, "inApp": true, "push": true },
      "paymentReceived": { "email": true, "inApp": true, "push": false }
    }
  }'

Push notifications

To receive push notifications, register a device token:

curl -X POST https://api.storno.ro/api/v1/devices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "firebase_device_token_here",
    "platform": "android"
  }'

Supported platforms: ios, android, web.

Invoice Events (Audit Log)

Each invoice maintains a history of status changes and significant events:

curl https://api.storno.ro/api/v1/invoices/{uuid}/events \
  -H "Authorization: Bearer {token}" \
  -H "X-Company: {company_uuid}"

[
  {
    "type": "status_change",
    "status": "issued",
    "timestamp": "2026-02-15T10:30:00Z",
    "details": "Invoice issued by [email protected]"
  },
  {
    "type": "status_change",
    "status": "sent_to_provider",
    "timestamp": "2026-02-15T10:31:00Z",
    "details": "Submitted to ANAF (upload ID: 12345)"
  },
  {
    "type": "status_change",
    "status": "validated",
    "timestamp": "2026-02-15T11:00:00Z",
    "details": "Validated by ANAF"
  }
]