Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jalmargyyk/ripe-updater/llms.txt

Use this file to discover all available pages before exploring further.

RIPE Updater exposes a small HTTP API built on Flask. Most operators only interact with two endpoints: /health for readiness probes and /update to receive NetBox webhook events. The /backups and /backup/<name> endpoints are available when S3 backup storage is enabled and give you a quick way to browse and retrieve stored RIPE object snapshots without leaving your browser.

​
GET /health

Returns the string Ok with HTTP 200 whenever the Flask process is running and accepting connections. No authentication is required. Use cases
  • Load balancer readiness and liveness probes
  • Uptime monitors and alerting systems
  • Confirming the container started correctly after deployment
curl http://your-ripe-updater-host/health

Ok

​
POST /update

The primary webhook receiver. NetBox calls this endpoint whenever a prefix is created, updated, or deleted. RIPE Updater validates the payload, looks up additional data from NetBox, builds a RIPE INETNUM or INET6NUM object from your templates, and pushes the change to the RIPE database.

​
Authentication

When UPDATE_TOKEN is set, every request must include the Authorisation header (British spelling) containing the configured token value. Requests that omit the header or supply a wrong value are rejected with 401. When UPDATE_TOKEN is not set, no token check is performed and all requests are accepted. 
Authorisation: Token <UPDATE_TOKEN>
The header name uses the British spelling Authorisation — not the American “Authorization”. NetBox must be configured with exactly this spelling in its additional headers, otherwise every webhook will be rejected with a 401 when UPDATE_TOKEN is set.

​
Request

  • Content-Type: application/json
  • Body: NetBox webhook JSON payload

​
Body parameters

​
model
string
required
The NetBox object type. Must be "prefix". Any other value returns 400.
​
event
string
required
The webhook event type. Accepted values are "created", "updated", and "deleted".
​
data.prefix
string
required
The IP prefix in CIDR notation, for example "192.0.2.0/24" or "2001:db8::/32".
​
data.custom_fields.ripe_report
boolean
required
Controls whether this prefix should be synchronised to the RIPE database. When false (or absent), RIPE Updater deletes the corresponding RIPE object. When true, it creates or updates it.
​
data.custom_fields.ripe_template
string
The template name to use when building the RIPE object. Required when ripe_report is true. Must match a key in your templates.json file (case-insensitive; stored uppercased internally). Omitting this when ripe_report is true returns 400.
​
data.site.slug
string
The NetBox site slug for the prefix. Used to look up the site’s parent region and derive the ISO 3166 country code for the RIPE object. If absent or the region cannot be resolved, DEFAULT_COUNTRY is used as a fallback.
​
username
string
The NetBox username who triggered the webhook. Included in email reports when MAIL_REPORT=yes. Defaults to "None" if not present.

​
Example payload

{
  "model": "prefix",
  "event": "created",
  "username": "jsmith",
  "data": {
    "prefix": "203.0.113.0/24",
    "site": {
      "slug": "amsterdam-dc1"
    },
    "custom_fields": {
      "ripe_report": true,
      "ripe_template": "CLOUD-POOL"
    }
  }
}

​
Response codes

CodeMeaning
204Success. The RIPE database operation completed and no body is returned.
400Invalid payload — missing required fields, wrong model value, or non-JSON body.
401Missing or incorrect Authorisation header.
500The RIPE database operation failed (e.g. a BadRequest or RipeDBError was raised).
Two additional responses return HTTP 200 rather than an error, because the skip is intentional: NotRoutedNetwork, skipping request when the prefix is RFC1918, loopback, link-local, multicast, or otherwise non-routable; and ErrorSmallPrefix, skipping request when the prefix length exceeds SMALLEST_PREFIX_V4 or SMALLEST_PREFIX_V6.

​
Example request

curl -X POST https://your-ripe-updater-host/update \
  -H "Authorisation: Token mysecrettoken" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "prefix",
    "event": "created",
    "username": "jsmith",
    "data": {
      "prefix": "203.0.113.0/24",
      "site": {
        "slug": "amsterdam-dc1"
      },
      "custom_fields": {
        "ripe_report": true,
        "ripe_template": "CLOUD-POOL"
      }
    }
  }'

​
GET /backups

Returns an HTML page listing all RIPE object backup files stored in S3. No authentication is required. The page is rendered from the backups.html template and shows the filename of every object stored in the configured S3 bucket. Each entry links to GET /backup/<name> so you can retrieve the raw JSON.
This endpoint returns an empty list when S3_BACKUP is not set to yes. Configure S3_ENDPOINT_URL, S3_ACCESS_KEY, S3_SECRET_ACCESS_KEY, and S3_BUCKET before enabling backups.
curl http://your-ripe-updater-host/backups

​
GET /backup/<name>

Returns the raw JSON content of a single backup file from S3. No authentication is required.

​
Path parameter

​
name
string
required
The filename of the backup object as it appears in the /backups listing. Filenames follow the pattern prefix_<cidr-with-slashes-replaced-by-underscores>.json, for example prefix_203.0.113.0_24.json.
curl http://your-ripe-updater-host/backup/prefix_203.0.113.0_24.json
The response body is the raw RIPE REST API JSON that was stored at the time the object was overwritten or deleted. You can pipe this directly to curl to restore the object to the RIPE database: 
curl -X POST \
  -H 'Content-Type: application/json' \
  --data @prefix_203.0.113.0_24.json \
  'https://rest.db.ripe.net/ripe/inetnum?password=RIPE_MNT_PASSWORD'
When S3_BACKUP=no, GET /backup/<name> returns an empty body regardless of the filename supplied.

Build docs developers (and LLMs) love

Get started for freeTalk to us