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
- Open Account settings in the dashboard.
- Enter your endpoint URL under Notification Webhook and save. The URL must start with
https://and can be up to 500 characters long. - After the first save, the dashboard shows your webhook secret. Store it on your server, for example in the
RATEFLOW_WEBHOOK_SECRETenvironment 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:
{
"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:
{
"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:
{
"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
// 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);
// 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);
# 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
2xxstatus 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.