API Reference

curl -X POST https://notify.trovido.com/api/notifyhub/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Mario Rossi",
      "email": "[email protected]"
    },
    "template": "hello_world",
    "channel": "email",
    "vars": { "name": "Mario" }
  }'

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://notify.trovido.com/api/notifyhub/v1/send', [
        'recipient' => ['name' => 'Mario', 'email' => '[email protected]'],
        'template'  => 'hello_world',
        'channel'   => 'email',
        'vars'      => ['name' => 'Mario'],
    ]);

const res = await fetch('https://notify.trovido.com/api/notifyhub/v1/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    recipient: { name: 'Mario', email: '[email protected]' },
    template: 'hello_world',
    channel: 'email',
    vars: { name: 'Mario' },
  }),
});

import requests

r = requests.post('https://notify.trovido.com/api/notifyhub/v1/send',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'recipient': {'name': 'Mario', 'email': '[email protected]'},
        'template': 'hello_world',
        'channel': 'email',
        'vars': {'name': 'Mario'},
    })

{
  "status": "queued",
  "delivery_id": 12345,
  "channel": "email",
  "recipient": { "id": 1, "name": "Mario Rossi" },
  "template": "hello_world"
}

{
  "recipient": { "name": "Mario", "email": "[email protected]" },
  "template": "order_confirmed",
  "channel": "email",
  "vars": { "order_id": "ORD-2024-1234" }
}

{
  "recipient": { "whatsapp_phone": "+393331234567" },
  "template": "review_request",
  "channel": "whatsapp",
  "actions": [
    { "slug": "approve", "label": "Pubblica",
      "callback_url": "https://sito.it/api/review/456" },
    { "slug": "reject", "label": "Rifiuta",
      "callback_url": "https://sito.it/api/review/456" }
  ]
}

{
  "recipient": { "telegram_chat_id": "624419126" },
  "template": "alert_critical",
  "channel": "telegram",
  "priority": "high",
  "vars": { "service": "Mailer", "error": "SMTP timeout" }
}

{
  "messages": [
    { "recipient": { "id": 1 }, "template": "weekly_digest", "channel": "email" },
    { "recipient": { "id": 2 }, "template": "weekly_digest", "channel": "telegram" },
    { "recipient": { "id": 3 }, "template": "weekly_digest", "channel": "whatsapp" }
  ]
}

{
  "total": 3,
  "queued": 3,
  "failed": 0,
  "results": [
    { "index": 0, "status": "queued", "delivery_id": 101 },
    { "index": 1, "status": "queued", "delivery_id": 102 },
    { "index": 2, "status": "queued", "delivery_id": 103 }
  ]
}

{
  "recipient": { "whatsapp_phone": "+393331234567" },
  "template": "review_approval",
  "channel": "whatsapp",
  "vars": { "1": "Mario Rossi", "2": "5 stelle", "3": "Ottimo servizio!" },
  "media": {
    "url": "https://example.com/photo.jpg",
    "type": "image"
  }
}

{
  "recipient": { "email": "[email protected]" },
  "template": "report_monthly",
  "channel": "email",
  "attachments": [
    {
      "url": "https://sito.it/reports/apr-2026.pdf",
      "filename": "report-aprile.pdf",
      "mime_type": "application/pdf"
    }
  ]
}

{
  "plan_slug": "nh-pro",
  "plan_name": "Pro",
  "messages": { "used": 1234, "limit": 10000, "remaining": 8766, "percentage": 12 },
  "whatsapp": { "used": 45, "limit": null },
  "period_start": "2026-04-01",
  "period_end": "2026-04-30"
}

{
  "status": "healthy",
  "worker": "active",
  "queue_depth": 0,
  "last_hour": { "sent": 12, "delivered": 11, "failed": 1 },
  "timestamp": "2026-04-29T20:38:52+00:00"
}

POST https://tuo-sito.it/webhook/notifyhub
X-NotifyHub-Signature: a1b2c3d4e5...
X-NotifyHub-Event: delivery.delivered
Content-Type: application/json

{
  "event": "delivery.delivered",
  "timestamp": "2026-04-29T15:30:00+00:00",
  "delivery": {
    "id": 12345,
    "status": "delivered",
    "recipient_id": 1,
    "channel": "whatsapp",
    "template_slug": "review_request",
    "external_id": "wamid.abc123",
    "error_message": null,
    "created_at": "2026-04-29T15:29:55+00:00"
  }
}

$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_NOTIFYHUB_SIGNATURE'];
$expected = hash_hmac('sha256', $body, $secret);

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

POST https://tuo-sito.it/api/reviews/456/moderate
X-Notifyhub-Signature: sha256=abc123...
X-Notifyhub-Timestamp: 1714000000
Content-Type: application/json

{
  "delivery_id": 12345,
  "action_slug": "approve",
  "payload": { "review_id": 456 },
  "actor": { "name": "Mario", "channel": "whatsapp" }
}

$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_NOTIFYHUB_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_NOTIFYHUB_TIMESTAMP'] ?? '';

// Rifiuta richieste oltre 5 minuti
if (abs(time() - (int) $timestamp) > 300) {
    abort(403, 'Request too old');
}

$expected = 'sha256=' . hash_hmac('sha256', $body, $yourApiKey);

if (!hash_equals($expected, $signature)) {
    abort(403, 'Invalid signature');
}

$data = json_decode($body, true);
// Processa: $data['action_slug'], $data['payload'], etc.

{
  "status": "validation_failed",
  "message": "The given data was invalid.",
  "details": {
    "recipient": ["The recipient field is required."],
    "template": ["The template field is required."]
  }
}

{
  "error": "quota_exceeded",
  "message": "Monthly quota reached (500/500). Buy credits or upgrade.",
  "used": 500,
  "limit": 500,
  "hint": "credits_empty"
}

{
  "status": "queued",
  "delivery_id": 1234,
  "channel": "whatsapp",
  "overage": {
    "credits_deducted": 3,
    "channel_cost": 3
  }
}

Se la quota mensile è esaurita ma hai crediti, il messaggio viene inviato e i crediti scalati. Costi: Telegram/Email 1 cr, WhatsApp 3 cr, SMS 10 cr.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
Retry-After: 3600