Webhooks
Instead of polling, register an HTTPS endpoint and receive a signed POST when something happens, for example when a document is ready. Deliveries follow the Standard Webhooks specification, so an off-the-shelf library can verify them.
Who can manage endpoints: see Who can manage integrations. In short, portal owners and admins, or an API key with webhooks:write on a management key.
Set up an endpoint
-
Add the endpoint. In the portal, open Settings → Integrations → Webhooks and choose Add endpoint. With the API:
curl -X POST "https://api.infus.ai/v1/webhooks" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/platform",
"events": ["knowledge.document.ready", "knowledge.document.failed"],
"description": "Ingestion tracker"
}' -
Save the secret. The response (
201) containssecret(whsec_…). It is shown only this once. Afterwards the API returns onlysecret_hint, its last four characters. -
Verify every request with the secret, as shown in Verify the signature.
-
Send a test event to check your receiver: Send test event on the endpoint page, or
POST /v1/webhooks/{webhook_id}:test. -
Answer fast. Reply with any
2xxwithin 10 seconds and do the real work afterwards.
Events
| Event | Sent when |
|---|---|
knowledge.document.ready | A document version becomes the searchable version: a first upload, a replacement, or a page of a website source |
knowledge.document.failed | A document version fails. For a failed replacement the previous version stays ready |
knowledge.document.deleted | A document deletion is accepted. Also sent for every document of a deleted knowledge base |
knowledge.export.ready | An export zip is ready to download |
knowledge.source.sync_completed | A website source's sync run ended, whatever the result. Exactly one per run |
knowledge.source.blocked | A website source was blocked by the site or stopped by the platform |
integrations.connection.reauth_required | A connection stopped working and needs someone to sign in again (connections are not available yet) |
integrations.webhook.test | You asked for a test event. It goes only to that endpoint and cannot be subscribed |
The data of each knowledge event is described in Knowledge Webhooks. The older /v1/knowledge_webhooks route is removed (404 not_found): knowledge events are delivered only to the endpoints on this page. GET /v1/webhook_event_types lists the events with their current version. New event types may be added later: ignore types you do not know.
Domain verification changes are not sent as webhooks. Watch them with GET /v1/domains; the organization owner also gets an email when a verification is lost. See Domains.
integrations.connection.reauth_required carries connection_id, platform and reason (credential_invalid or refresh_failed). integrations.webhook.test carries webhook_id and a fixed message.
Payload
Every delivery is POST <your url> with Content-Type: application/json and User-Agent: Infus-Webhooks/1. The body is at most 16 KB:
{
"id": "5b0f2c44-2f39-5d8e-9a51-7c3e0d4b6a21",
"type": "knowledge.document.ready",
"version": 1,
"scope": "tenant",
"tenant_id": "9d2e4b1a-7c3f-4e5d-8a6b-1c2d3e4f5a6b",
"occurred_at": "2026-10-07T10:00:00.101010Z",
"created_at": "2026-10-07T10:00:00.123456Z",
"data": {
"knowledge_base_id": "3f6c2b1e-8d4a-4c1f-9e2b-7a5d6c3b2a10",
"document_id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"origin": "upload",
"source_id": null,
"status": "ready",
"name": "handbook.pdf",
"size_bytes": 1832211,
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"failure": null
}
}
| Field | Meaning |
|---|---|
id | The event id, also sent as the webhook-id header. The same for every endpoint, every retry and every redelivery of the same event. Deduplicate on it. |
type | The event type |
version | The version of the data layout for this type (see Event versions) |
scope | Always tenant for events you receive |
tenant_id | Your organization's id |
occurred_at | When the change happened. Deliveries can arrive out of order: use this to order events |
created_at | When the event was recorded |
data | The event's fields. Ignore fields you do not know: new fields may be added |
Payloads never contain document text, metadata values, secrets or download links.
Verify the signature
Every attempt carries three headers:
| Header | Value |
|---|---|
webhook-id | The event id |
webhook-timestamp | Unix seconds of this attempt |
webhook-signature | v1,<base64 signature>. During a secret rotation, two entries separated by a space, the new secret first |
The signature is computed over the raw body:
base64( HMAC-SHA256( key = base64-decode(secret without "whsec_"),
message = "{webhook-id}.{webhook-timestamp}.{raw request body}" ) )
Your receiver must:
- Compute the signature over the raw body bytes, before any JSON parsing.
- Compare it in constant time with every
v1,entry ofwebhook-signature, and accept if any matches. - Reject the request if
webhook-timestampis more than 300 seconds away from your clock. - Skip events whose
webhook-idyou have already processed: delivery is at least once.
Python, with the Standard Webhooks library
# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook
wh = Webhook("whsec_…") # the endpoint's secret
def handle(raw_body: bytes, headers: dict) -> None:
event = wh.verify(raw_body, headers) # raises on a bad signature or an old timestamp
if already_processed(event["id"]):
return
...
Python, without a library
import base64
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 300
def verify(secret: str, headers, raw_body: bytes) -> bool:
"""headers: the request headers (a case-insensitive mapping, as in Flask)."""
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
if not (timestamp.isascii() and timestamp.isdigit() and len(timestamp) <= 12):
return False
if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
for entry in signatures.split(" "):
version, _, signature = entry.partition(",")
if version == "v1" and hmac.compare_digest(signature.encode(), expected):
return True
return False
With Flask, pass request.headers and request.get_data():
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/platform")
def receive():
if not verify(WEBHOOK_SECRET, request.headers, request.get_data()):
abort(400)
event = request.get_json()
# deduplicate on event["id"], queue the work, answer at once
return "", 204
Node.js
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 300;
export function verify(secret, headers, rawBody /* Buffer */) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = Buffer.from(
crypto.createHmac("sha256", key).update(`${id}.${timestamp}.`).update(rawBody).digest("base64"),
);
return signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature) return false;
const received = Buffer.from(signature);
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
With Express, read the body with express.raw so you verify the exact bytes that were signed:
import express from "express";
const app = express();
app.post("/platform", express.raw({ type: "application/json" }), (req, res) => {
if (!verify(process.env.WEBHOOK_SECRET, req.headers, req.body)) return res.sendStatus(400);
const event = JSON.parse(req.body);
// deduplicate on event.id, queue the work, answer at once
res.sendStatus(204);
});
Retries and automatic disable
An attempt succeeds on any 2xx within the timeout: 5 seconds to connect, 10 seconds in total. Everything else fails the attempt: other statuses, redirects (never followed), timeouts, TLS or connection errors, or a URL that now breaks the endpoint rules. Response bodies are read up to 64 KB and thrown away. Up to 4 deliveries to one endpoint run at the same time.
Failed deliveries are retried after these delays (±10 % jitter):
| Attempt | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|
| Delay | immediately | 1 min | 5 min | 15 min | 1 h | 2 h | 4 h | 8 h | 8 h |
If no attempt succeeded 24 hours after the first one, the delivery is dropped.
An endpoint is turned off automatically when one of its deliveries is dropped and nothing to that endpoint succeeded since that delivery's first attempt. In practice that is about 24 hours of continuous failure. Then:
enabledbecomesfalse,disabled_reasonisdelivery_failuresanddisabled_atrecords the time. An endpoint you turn off yourself showsdisabled_reason: customer;- its pending deliveries are dropped;
- the organization owner gets an email.
To recover: fix the receiver, send a test event (it works on an endpoint that is off), then turn the endpoint back on (PATCH /v1/webhooks/{webhook_id} with {"enabled": true}). Events dropped meanwhile are not sent again on their own: send them again from the delivery list (below).
Deliveries, test events and redelivery
Each endpoint keeps its delivery history for 30 days: the event, status, number of attempts, the HTTP status of the last attempt and the ids the event is about (references). Response bodies are never stored.
curl "https://api.infus.ai/v1/webhooks/$WEBHOOK_ID/deliveries?status=dropped" \
-H "Authorization: Bearer $API_KEY"
status | Portal | Meaning |
|---|---|---|
pending | Sending | Not attempted yet |
succeeded | Delivered | A 2xx was received |
failed | Retrying | The last attempt failed; more attempts are scheduled |
dropped | Failed | Gave up after 24 hours, or the endpoint was turned off or deleted |
- Send again:
POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}:redeliver(portal: Send again) sends the same event, with the sameid, as a new delivery. It works for asucceededordroppeddelivery whose event is less than 30 days old, while the endpoint is on; otherwise409 redelivery_unavailable. At most 60 per endpoint per hour. - Test event:
POST /v1/webhooks/{webhook_id}:testsendsintegrations.webhook.testthrough the normal path. The delivery showsis_test: trueand never counts towards automatic disable. At most 10 per endpoint per hour (429 webhook_test_rate_limited).
Rotate the secret
POST /v1/webhooks/{webhook_id}:rotate_secret (portal: Rotate secret) returns a new secret, shown once, and previous_secret_expires_at. For the next 24 hours every delivery is signed with both secrets, the new one first, so you can deploy the new secret without missing events. Then the old secret is destroyed.
- Only two secrets can be live. Rotating again during the 24 hours answers
409 secret_rotation_in_progress, unless you send{"expire_previous_now": true}: the older secret is then destroyed at once. - Lost the secret? Creating an endpoint and rotating are never replayed: the plaintext secret is not kept after the response. List your endpoints, find the one you created, and rotate with
{"expire_previous_now": true}.
Endpoint rules
URLs are checked when you add them (422 webhook_url_rejected, with the rule in details.rule) and again before every attempt, after DNS resolution:
httpsonly, with a valid certificate, on port 443 (implicit or:443); nouser:password@; at most 2,048 characters.- A public DNS name: no IP addresses, single-label names or internal suffixes such as
.localor.internal. - Every address the name resolves to must be public. Private, loopback, link-local (including cloud metadata addresses), carrier-grade NAT, multicast and reserved ranges are refused.
- A host your platform operator has blocked is refused (
details.rule: domain_blocked). - Redirects are not followed and proxies are not used.
Limits
| Limit | Value |
|---|---|
| Endpoints per organization | 10 by default; your platform operator sets it (409 webhook_limit, details.limit) |
| Events per endpoint | 1 to 64 |
| Description | 256 characters |
| Payload | 16 KB |
| Delivery history | 30 days |
| Test events | 10 per endpoint per hour |
| Redeliveries | 60 per endpoint per hour |
Manage endpoints
| Operation | Endpoint |
|---|---|
| List / get | GET /v1/webhooks, GET /v1/webhooks/{webhook_id} |
| Change URL, events, description, event versions, on/off | PATCH /v1/webhooks/{webhook_id} |
| Delete (pending deliveries are dropped, secrets destroyed) | DELETE /v1/webhooks/{webhook_id} |
| Rotate the secret | POST /v1/webhooks/{webhook_id}:rotate_secret |
| Send a test event | POST /v1/webhooks/{webhook_id}:test |
| Delivery history | GET /v1/webhooks/{webhook_id}/deliveries, GET …/deliveries/{delivery_id} |
| Send a delivery again | POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}:redeliver |
| Event types | GET /v1/webhook_event_types |
Every field is in the Integrations API Reference.
Event versions
Each endpoint receives one data layout per event type, shown in its event_versions (for example {"knowledge.document.ready": 1}). Every type is at version 1 today. A change that is not backwards compatible gets a new version: both versions are then offered for at least 90 days, and you move an endpoint to the new one with PATCH /v1/webhooks/{webhook_id} and event_versions.
Errors
| Code | Status | Meaning |
|---|---|---|
webhook_limit | 409 | The organization has the maximum number of endpoints (details.limit) |
webhook_url_rejected | 422 | The URL breaks an endpoint rule (details.rule). The URL is never echoed |
event_type_unknown | 422 | events names a type you cannot subscribe to (param = events[i]) |
secret_rotation_in_progress | 409 | The previous secret is still live (details.previous_secret_expires_at) |
redelivery_unavailable | 409 | The delivery is still pending or retrying, its event is older than 30 days, or the endpoint is off |
webhook_test_rate_limited | 429 | More than 10 test events per endpoint per hour |
kb_not_in_allowlist | 403 | The API key is limited to a list of knowledge bases |
The codes every area shares are in the overview.