ff-agent-api-client

FF-Agent Ticker Gateway

Receives Einsätze (operations/incidents) from FF-Agent via webhook and keeps a local JSON file for a ticker-style microsite. You can also import existing data from a CSV export.

Requirements

• Python 3.8+
• Dependencies: flask, PyYAML, requests (see requirements.txt)

Installation

pip install -r requirements.txt

Webhook receiver

FF-Agent can push Einsatz details to a URL. Run the webhook server so it accepts POSTs and updates the JSON file.

Start the server (default: port 5000, data file data/einsaetze.json):

python webhook_receiver.py

Options:

python webhook_receiver.py --host 0.0.0.0 --port 8080 --data data/einsaetze.json

Option	Default	Description
--host	0.0.0.0	Bind address.
--port	5000	Port.
--data	data/einsaetze.json	Path to the JSON file to read/write.

Environment: Set EINSATZ_JSON_PATH to override the data file path without --data.

Endpoints:

• POST /webhook or POST / – Accepts JSON:
  • A single Einsatz object, or
  • { "einsaetze": [ ... ] } with an array of Einsätze.
• GET / or GET /health – Health check; returns data_path and status.

Merge behaviour: Incoming records are merged by operationId. If an ID already exists, that record is updated; otherwise it is appended. The file is written after each successful POST.

Configuring FF-Agent: In FF-Agent set the webhook URL to your server, e.g. https://your-server.example.com/webhook. Ensure the server is reachable (firewall, reverse proxy, HTTPS if needed).

PHP webhook receiver

A PHP script accepts POST requests with a JSON body and appends the payload to the same data file without assuming a fixed structure.

Run it: Point your web server (Apache/Nginx) at webhook_receiver.php for the webhook URL, or use the built-in server for local testing:

php -S 0.0.0.0:8080

Then send POST requests to http://localhost:8080/webhook_receiver.php with Content-Type: application/json.

Behaviour: The raw POST body is decoded as JSON and stored in data/einsaetze.json under the root key webhook_events: each event is { "received": "<ISO8601 UTC>", "data": <your payload> }. The root key updated is set to the time of the last webhook write. The einsaetze array is left unchanged by the webhook. Set the environment variable EINSATZ_JSON_PATH to override the data file path (default: data/einsaetze.json). Request body is limited to 1 MB.

CSV import

To seed or replace data from an FF-Agent CSV export (semicolon-delimited):

python import_einsaetze_csv.py Einsatzexport_2026-02-03-21-15-53.csv -o data/einsaetze.json

Same output format as the webhook (see below). You can run the CSV import once, then run the webhook receiver so new events update the same file.

Output format

Both the webhook and the CSV importer use this JSON structure:

• einsaetze – Array of Einsatz objects (fields depend on FF-Agent / CSV columns).
• updated – ISO 8601 timestamp (UTC) of the last write.
• webhook_events – (PHP webhook only) Array of { "received": "<ISO8601>", "data": <payload> } for each POST.

Example:

{
  "einsaetze": [
    {
      "operationId": "T 1.1 260202 828",
      "keyword": "THL 1 T2714",
      "message": "klein Fahrzeug öffnen",
      "location": "Vimystraße 3",
      "district": "85356 Freising"
    }
  ],
  "updated": "2026-02-03T20:30:00.123456+00:00"
}

The ticker service reads this file and uses einsaetze; updated can be used for display or cache invalidation.

Files

File	Purpose
webhook_receiver.php	PHP webhook: POST JSON → append to webhook_events in data file.
webhook_receiver.py	Webhook server: POST → merge into JSON.
import_einsaetze_csv.py	Import CSV export into the same JSON format.
requirements.txt	Python dependencies.
data/einsaetze.json	Data file (created/updated by webhook or import).
Dokumentation_WebAPI_ffagent.pdf	FF-Agent WebAPI documentation.