Skip to main content

API Webhooks

Real-time event notifications via HTTP webhooks.

Overview​

Webhooks allow external systems to receive real-time notifications when subscriber session events occur in AthenaBNG. When an event fires, AthenaBNG sends an HTTP POST request to your registered webhook URL.

Webhooks are stored in-memory and do not persist across API restarts. Re-register webhooks after a restart if needed.

Managing Webhooks​

All webhook management requires an admin role JWT token.

Register a Webhook​

curl -sk -X POST https://localhost:8443/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/bng",
    "events": ["session.up", "session.down"]
  }'

Response:

{
  "status": "ok",
  "data": {
    "id": "a1b2c3d4",
    "url": "https://your-server.com/webhooks/bng",
    "events": ["session.up", "session.down"]
  }
}

List Registered Webhooks​

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/webhooks

Response:

{
  "status": "ok",
  "data": {
    "webhooks": [
      {
        "id": "a1b2c3d4",
        "url": "https://your-server.com/webhooks/bng",
        "events": ["session.up", "session.down"]
      }
    ],
    "count": 1
  }
}

Delete a Webhook​

curl -sk -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/webhooks/a1b2c3d4

Errors: 404 if the webhook ID does not exist.

Event Types​

session.up​

Fired when a subscriber PPPoE or DHCP session is established.

{
  "event": "session.up",
  "timestamp": "2026-03-14T12:00:00Z",
  "data": {
    "id": 1,
    "type": "PPPoE",
    "username": "user1@isp",
    "ip_address": "203.0.113.10",
    "interface": "trunk0.200.20"
  }
}

session.down​

Fired when a subscriber session is terminated (user request, admin disconnect, timeout).

{
  "event": "session.down",
  "timestamp": "2026-03-14T12:05:00Z",
  "data": {
    "id": 1,
    "username": "user1@isp",
    "reason": "user_request"
  }
}

Delivery​

Request Format​

AthenaBNG delivers events as HTTP POST requests with a JSON body:

POST /webhooks/bng HTTP/1.1
Host: your-server.com
Content-Type: application/json
User-Agent: AthenaBNG-Webhook/1.0

{
  "event": "session.up",
  "timestamp": "2026-03-14T12:00:00Z",
  "data": { ... }
}

Expected Response​

Return any 2xx status code to acknowledge receipt. Any other status code is treated as a delivery failure.

Retry Policy​

If delivery fails (non-2xx response or connection error):

  • 1st retry after 5 seconds
  • 2nd retry after 30 seconds
  • 3rd retry after 5 minutes
  • Webhook is skipped for this event after 3 failed attempts

Server-Sent Events Alternative​

For real-time event streaming without webhook registration, use the SSE endpoint:

curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/events/subscribers

This opens a persistent connection and streams events as they occur. Useful for dashboards and monitoring tools.

Example Webhook Handler​

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhooks/bng")
async def handle_bng_event(request: Request):
    event = await request.json()

    if event["event"] == "session.up":
        print(f"Session up: {event['data']['username']} -> {event['data']['ip_address']}")
    elif event["event"] == "session.down":
        print(f"Session down: {event['data']['username']}")

    return {"status": "ok"}

Next Steps​