Skip to main content

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​

  1. 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"
    }'
  2. Save the secret. The response (201) contains secret (whsec_…). It is shown only this once. Afterwards the API returns only secret_hint, its last four characters.

  3. Verify every request with the secret, as shown in Verify the signature.

  4. Send a test event to check your receiver: Send test event on the endpoint page, or POST /v1/webhooks/{webhook_id}:test.

  5. Answer fast. Reply with any 2xx within 10 seconds and do the real work afterwards.

Events​

EventSent when
knowledge.document.readyA document version becomes the searchable version: a first upload, a replacement, or a page of a website source
knowledge.document.failedA document version fails. For a failed replacement the previous version stays ready
knowledge.document.deletedA document deletion is accepted. Also sent for every document of a deleted knowledge base
knowledge.export.readyAn export zip is ready to download
knowledge.source.sync_completedA website source's sync run ended, whatever the result. Exactly one per run
knowledge.source.blockedA website source was blocked by the site or stopped by the platform
integrations.connection.reauth_requiredA connection stopped working and needs someone to sign in again (connections are not available yet)
integrations.webhook.testYou 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
}
}
FieldMeaning
idThe 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.
typeThe event type
versionThe version of the data layout for this type (see Event versions)
scopeAlways tenant for events you receive
tenant_idYour organization's id
occurred_atWhen the change happened. Deliveries can arrive out of order: use this to order events
created_atWhen the event was recorded
dataThe 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:

HeaderValue
webhook-idThe event id
webhook-timestampUnix seconds of this attempt
webhook-signaturev1,<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:

  1. Compute the signature over the raw body bytes, before any JSON parsing.
  2. Compare it in constant time with every v1, entry of webhook-signature, and accept if any matches.
  3. Reject the request if webhook-timestamp is more than 300 seconds away from your clock.
  4. Skip events whose webhook-id you 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):

Attempt123456789
Delayimmediately1 min5 min15 min1 h2 h4 h8 h8 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:

  • enabled becomes false, disabled_reason is delivery_failures and disabled_at records the time. An endpoint you turn off yourself shows disabled_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"
statusPortalMeaning
pendingSendingNot attempted yet
succeededDeliveredA 2xx was received
failedRetryingThe last attempt failed; more attempts are scheduled
droppedFailedGave 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 same id, as a new delivery. It works for a succeeded or dropped delivery whose event is less than 30 days old, while the endpoint is on; otherwise 409 redelivery_unavailable. At most 60 per endpoint per hour.
  • Test event: POST /v1/webhooks/{webhook_id}:test sends integrations.webhook.test through the normal path. The delivery shows is_test: true and 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:

  • https only, with a valid certificate, on port 443 (implicit or :443); no user:password@; at most 2,048 characters.
  • A public DNS name: no IP addresses, single-label names or internal suffixes such as .local or .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​

LimitValue
Endpoints per organization10 by default; your platform operator sets it (409 webhook_limit, details.limit)
Events per endpoint1 to 64
Description256 characters
Payload16 KB
Delivery history30 days
Test events10 per endpoint per hour
Redeliveries60 per endpoint per hour

Manage endpoints​

OperationEndpoint
List / getGET /v1/webhooks, GET /v1/webhooks/{webhook_id}
Change URL, events, description, event versions, on/offPATCH /v1/webhooks/{webhook_id}
Delete (pending deliveries are dropped, secrets destroyed)DELETE /v1/webhooks/{webhook_id}
Rotate the secretPOST /v1/webhooks/{webhook_id}:rotate_secret
Send a test eventPOST /v1/webhooks/{webhook_id}:test
Delivery historyGET /v1/webhooks/{webhook_id}/deliveries, GET …/deliveries/{delivery_id}
Send a delivery againPOST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}:redeliver
Event typesGET /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​

CodeStatusMeaning
webhook_limit409The organization has the maximum number of endpoints (details.limit)
webhook_url_rejected422The URL breaks an endpoint rule (details.rule). The URL is never echoed
event_type_unknown422events names a type you cannot subscribe to (param = events[i])
secret_rotation_in_progress409The previous secret is still live (details.previous_secret_expires_at)
redelivery_unavailable409The delivery is still pending or retrying, its event is older than 30 days, or the endpoint is off
webhook_test_rate_limited429More than 10 test events per endpoint per hour
kb_not_in_allowlist403The API key is limited to a list of knowledge bases

The codes every area shares are in the overview.