Zum Inhalt springen
RateFlowAPI

Referenz

Webhooks

Auf dieser Seite

Mit einem Webhook informiert RateFlow Ihren Server, wenn in Ihrem Konto etwas passiert, zum Beispiel wenn Sie 80 % Ihres monatlichen Kontingents verbraucht haben. RateFlow sendet dazu eine HTTP-POST-Anfrage mit einem JSON-Body an eine URL Ihrer Wahl.

Einrichtung

  1. Öffnen Sie die Kontoeinstellungen im Dashboard.
  2. Tragen Sie unter Benachrichtigungs-Webhook die URL Ihres Endpunkts ein und speichern Sie. Die URL muss mit https:// beginnen und darf höchstens 500 Zeichen lang sein.
  3. Nach dem ersten Speichern zeigt das Dashboard Ihr Webhook-Secret. Speichern Sie es auf Ihrem Server, zum Beispiel in der Umgebungsvariable RATEFLOW_WEBHOOK_SECRET. Damit prüfen Sie, dass eine Anfrage wirklich von RateFlow kommt.

Mit Neu erzeugen erstellen Sie jederzeit ein neues Secret. Ereignisse, die danach passieren, werden mit dem neuen Secret signiert. Ereignisse von vorher behalten ihre alte Signatur und ihre alte URL, auch wenn sie noch auf den Versand oder eine Wiederholung warten. Akzeptieren Sie das alte Secret deshalb noch einige Minuten nach dem Neu-Erzeugen.

Wenn Sie die URL leeren und speichern, werden für neue Ereignisse keine Webhooks mehr gesendet und das Secret wird gelöscht.

Ereignisse

Ereignis Wird gesendet, wenn
quota.warning Ihre monatliche Nutzung eine Warnschwelle erreicht (standardmäßig 80 % Ihres Kontingents)
quota.exceeded Ihre monatliche Nutzung 100 % Ihres Kontingents erreicht
subscription.updated Sie von einem Plan zu einem anderen wechseln oder ein Downgrade geplant wird. Nicht beim Start Ihres ersten Abonnements
subscription.canceled Ihr bezahltes Abonnement beendet wurde. Nicht, wenn es wegen fehlgeschlagener Zahlungen endete
payment.failed Eine Zahlung für Ihr Abonnement fehlschlägt

RateFlow legt fest, welche Schwellen eine Meldung auslösen. Jede Schwelle wird normalerweise einmal pro Kalendermonat (UTC) gesendet. In seltenen Fällen kommt eine Meldung doppelt oder gar nicht, zum Beispiel bei einem kurzen Ausfall unseres Nutzungszählers. Verstehen Sie die Kontingent-Ereignisse deshalb als frühe Warnung und fragen Sie die genauen Zahlen beim Kontingent-Endpunkt ab.

Nutzdaten

Jede Nutzlast enthält das Feld event mit dem Namen des Ereignisses und das Feld timestamp mit dem Zeitpunkt der Erstellung im Format ISO 8601.

quota.warning und quota.exceeded:

JSON
{
    "event": "quota.warning",
    "threshold": 80,
    "usage": {
        "used": 1600,
        "base_limit": 2000,
        "effective_limit": 2000,
        "percentage": 80
    },
    "timestamp": "2026-10-25T14:03:11+00:00"
}
Feld Beschreibung
threshold Die erreichte Schwelle in Prozent
usage.used Die in diesem Monat gezählten Anfragen im Moment, in dem die Schwelle erreicht wurde. Die endgültige Zahl kann etwas niedriger sein, weil fehlgeschlagene Anfragen nicht berechnet werden
usage.base_limit Das monatliche Kontingent Ihres Plans
usage.effective_limit Das tatsächlich durchgesetzte Limit, einschließlich eines zusätzlichen Spielraums Ihres Plans
usage.percentage Gleich wie threshold

subscription.updated:

JSON
{
    "event": "subscription.updated",
    "plan": "Pro",
    "is_downgrade": true,
    "effective_at": "2026-11-01T00:00:00+00:00",
    "timestamp": "2026-10-25T14:03:11+00:00"
}
Feld Beschreibung
plan Der Anzeigename des neuen Plans
is_downgrade true bei einem Downgrade. Ein Planwechsel durch das RateFlow-Team hat immer false
effective_at Wann ein geplantes Downgrade wirksam wird, oder null, wenn die Änderung sofort gilt

subscription.canceled und payment.failed enthalten nur den Namen des Ereignisses und den Zeitpunkt:

JSON
{
    "event": "payment.failed",
    "timestamp": "2026-10-25T14:03:11+00:00"
}

Die Anfrage

RateFlow sendet eine POST-Anfrage mit diesen Headern:

Header Beschreibung
Content-Type Immer application/json
X-Webhook-Event Der Name des Ereignisses, gleich wie event im Body
X-Webhook-Signature sha256=, gefolgt vom HMAC-SHA256 des unveränderten Request-Bodys, erstellt mit Ihrem Webhook-Secret, als Hex in Kleinbuchstaben

Signatur prüfen

Prüfen Sie die Signatur, bevor Sie einer Anfrage vertrauen. Berechnen Sie den HMAC-SHA256 des unveränderten Bodys genau so, wie Sie ihn erhalten haben, mit Ihrem Webhook-Secret als Schlüssel. Vergleichen Sie das Ergebnis dann mit einem zeitkonstanten Vergleich mit dem Header X-Webhook-Signature. Parsen und kodieren Sie das JSON vorher nicht neu, denn eine andere Kodierung ergibt eine andere Signatur.

Jedes Beispiel unten ist ein kleiner Server auf Port 8000, der die Signatur prüft, den Namen des Ereignisses ausgibt und mit 204 No Content antwortet.

PHP
<?php
// Run with: php -S 0.0.0.0:8000 webhook.php
$secret = getenv('RATEFLOW_WEBHOOK_SECRET');
$body = file_get_contents('php://input');

$expected = 'sha256='.hash_hmac('sha256', $body, $secret);
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
error_log('RateFlow event: '.$event['event']);

http_response_code(204);
JavaScript
// Run with: node webhook.mjs (Node.js 18 or newer)
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const secret = process.env.RATEFLOW_WEBHOOK_SECRET;

createServer((req, res) => {
    const chunks = [];
    req.on('data', (chunk) => chunks.push(chunk));
    req.on('end', () => {
        const body = Buffer.concat(chunks);
        const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(body).digest('hex'));
        const received = Buffer.from(req.headers['x-webhook-signature'] ?? '');

        if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
            res.writeHead(401).end();
            return;
        }

        const event = JSON.parse(body);
        console.log('RateFlow event:', event.event);
        res.writeHead(204).end();
    });
}).listen(8000);
Python
# Run with: python3 webhook.py
import hashlib
import hmac
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["RATEFLOW_WEBHOOK_SECRET"].encode()


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
        received = self.headers.get("X-Webhook-Signature", "")

        if not hmac.compare_digest(expected, received):
            self.send_response(401)
            self.end_headers()
            return

        event = json.loads(body)
        print("RateFlow event:", event["event"])
        self.send_response(204)
        self.end_headers()


HTTPServer(("", 8000), Handler).serve_forever()

Zustellung und Wiederholungen

  • Antworten Sie mit einem beliebigen 2xx-Status, um eine Zustellung zu bestätigen. Jeder andere Status, eine Weiterleitung oder keine Antwort innerhalb von 10 Sekunden gilt als Fehlschlag.
  • RateFlow folgt keinen Weiterleitungen. Verwenden Sie die endgültige URL Ihres Endpunkts.
  • Eine fehlgeschlagene Zustellung wird nach etwa 10 Sekunden wiederholt und danach noch einmal nach etwa weiteren 60 Sekunden. Nach drei Fehlschlägen wird das Ereignis verworfen. Zustellungen laufen in einer Hintergrund-Warteschlange, daher sind diese Zeiten nicht exakt.
  • Eine Anfrage kann mehr als einmal ankommen, zum Beispiel wenn Ihr Server sie verarbeitet, aber zu spät geantwortet hat. Gestalten Sie Ihren Handler so, dass er dasselbe Ereignis gefahrlos zweimal verarbeiten kann.
  • Antworten Sie schnell und erledigen Sie langsame Arbeit danach, damit die Grenze von 10 Sekunden nie erreicht wird.
  • Der Endpunkt muss im öffentlichen Internet erreichbar sein. Wenn sich Ihr Hostname nicht auflösen lässt oder auf eine private, lokale oder reservierte Netzwerkadresse zeigt, wird das Ereignis ohne Wiederholung verworfen.