Docs API ReferenceConfigure and Use Webhooks

Configure and Use Webhooks

Set up webhooks to receive real-time notifications when server events occur in your LightYear account.

intermediate

8 min read

LightYear Docs Team

Updated April 24, 2026

webhookseventsnotificationsapiautomation

Webhooks allow LightYear to push real-time event notifications to your application when specific events occur, such as server status changes or billing events.

Supported Events

Event	Description
`server.created`	A new server was provisioned
`server.deleted`	A server was deleted
`server.status_changed`	Server status changed (active, stopped, etc.)
`snapshot.completed`	A snapshot finished creating
`backup.completed`	An automated backup completed
`invoice.created`	A new invoice was generated
`payment.processed`	A payment was processed

Create a Webhook Endpoint

Your webhook endpoint must:

Accept HTTP POST requests
Return HTTP 200 within 10 seconds
Be accessible from the internet

Example Node.js Endpoint

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.LIGHTYEAR_WEBHOOK_SECRET;

app.post('/webhooks/lightyear', (req, res) => {
  // Verify signature
  const signature = req.headers['x-lightyear-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== `sha256=${expected}`) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;
  
  switch (event) {
    case 'server.created':
      console.log(`New server: ${data.server.label} at ${data.server.main_ip}`);
      break;
    case 'server.status_changed':
      console.log(`Server ${data.server.label} is now ${data.server.status}`);
      break;
  }
  
  res.status(200).json({ received: true });
});

app.listen(3000);

Register a Webhook

>_BASH

$curl -X POST https://api.lightyear.host/v1/webhooks \
$  -H "Authorization: Bearer YOUR_API_KEY" \
$  -H "Content-Type: application/json" \
$  -d '{
$    "url": "https://your-app.example.com/webhooks/lightyear",
$    "events": ["server.created", "server.deleted", "server.status_changed"],
$    "secret": "your-webhook-secret"
$  }'

Webhook Payload Format

JSON

{
  "id": "evt_abc123",
  "event": "server.status_changed",
  "timestamp": "2026-04-24T10:00:00Z",
  "data": {
    "server": {
      "id": "srv_abc123",
      "label": "web-server-01",
      "status": "active",
      "main_ip": "45.77.x.x"
    }
  }
}

Retry Policy

If your endpoint returns a non-200 status or times out, LightYear retries the webhook with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the webhook delivery is abandoned and marked as failed.

[!TIP] Always respond with HTTP 200 immediately and process the event asynchronously (e.g., add it to a queue). This prevents timeouts from causing unnecessary retries.

Was this article helpful?