Skip to content
RateFlowAPI

Reference

Webhooks

On this page

A webhook lets RateFlow tell your server when something happens on your account, for example when you have used 80% of your monthly quota. RateFlow sends an HTTP POST request with a JSON body to a URL you choose.

Setup

  1. Open Account settings in the dashboard.
  2. Enter your endpoint URL under Notification Webhook and save. The URL must start with https:// and can be up to 500 characters long.
  3. After the first save, the dashboard shows your webhook secret. Store it on your server, for example in the RATEFLOW_WEBHOOK_SECRET environment variable. You need it to check that a request really comes from RateFlow.

You can create a new secret at any time with Regenerate. Events that happen after that are signed with the new secret. Events that happened before keep their old signature and their old URL, even if they are still waiting to be sent or retried. So keep accepting the old secret for a few minutes after you regenerate it.

If you clear the URL and save, no webhooks are sent for new events and the secret is deleted.

Events

Event Sent when
quota.warning Your monthly usage reaches a warning threshold (by default 80% of your quota)
quota.exceeded Your monthly usage reaches 100% of your quota
subscription.updated You move from one plan to another, or a downgrade is scheduled. Not sent when you start your first subscription
subscription.canceled Your paid subscription has ended. Not sent when it ended because payments failed
payment.failed A payment for your subscription fails

RateFlow decides which thresholds send an alert. Each threshold is normally sent once per calendar month (UTC). In rare cases an alert can arrive twice, or not at all, for example during a short outage of our usage counter. So treat the quota events as early warnings, and ask the Quota endpoint for the exact numbers.

Payloads

Every payload has an event field with the event name and a timestamp field with the time it was created, in ISO 8601 format.

quota.warning and 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"
}
Field Description
threshold The threshold that was reached, in percent
usage.used Requests counted this month at the moment the threshold was reached. The final number can be slightly lower, because failed requests are not billed
usage.base_limit Your plan's monthly quota
usage.effective_limit The limit that is enforced, including any extra allowance on your plan
usage.percentage Same as 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"
}
Field Description
plan The display name of the new plan
is_downgrade true for a downgrade. A plan change made by the RateFlow team always has false
effective_at When a scheduled downgrade takes effect, or null when the change applies at once

subscription.canceled and payment.failed carry only the event name and the time:

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

The Request

RateFlow sends a POST request with these headers:

Header Description
Content-Type Always application/json
X-Webhook-Event The event name, the same as event in the body
X-Webhook-Signature sha256= followed by the HMAC-SHA256 of the raw request body, made with your webhook secret, as lowercase hex

Verify the Signature

Check the signature before you trust a request. Compute the HMAC-SHA256 of the raw body exactly as you received it, with your webhook secret as the key. Then compare the result with the X-Webhook-Signature header using a constant-time comparison. Do not parse and re-encode the JSON first, because a different encoding gives a different signature.

Each example below is a small server on port 8000 that checks the signature, prints the event name and answers 204 No Content.

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()

Delivery and Retries

  • Answer with any 2xx status to confirm a delivery. Any other status, a redirect or no answer within 10 seconds counts as a failure.
  • RateFlow does not follow redirects. Use the final URL of your endpoint.
  • A failed delivery is tried again after about 10 seconds, and then once more after about another 60 seconds. After three failed attempts the event is dropped. Deliveries run in a background queue, so these times are not exact.
  • A request can arrive more than once, for example when your server handled it but answered too late. Make your handler safe to run twice for the same event.
  • Answer quickly and do slow work afterwards, so the 10-second limit is never reached.
  • The endpoint must be reachable on the public internet. If your host name does not resolve, or it points to a private, local or reserved network address, the event is dropped without retries.