Webhooks

Harbor & Pine's accounts system sends every new invoice to Suppliers & invoices as a record. It wants to know when each one is searchable, and to hear at once when one is not. Rather than asking again and again, it gives SynapseOrch Cloud a URL to call: a webhook endpoint. Each time a document in the workspace is indexed, partly indexed or fails, or a base switches to a rebuilt index, Synapse sends one signed POST there.

Webhooks are a SynapseOrch Cloud feature, managed through the API with an API key; there is no screen for them yet. They are not the webhook_url a single run can carry, which calls back once when that run ends — see Be called when it ends.

1. Add an endpoint

curl -X POST https://api.synapseorch.com/api/v1/webhooks \
  -H "Authorization: Bearer $SYNAPSE_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://accounts.harborpine.example/hooks/synapse",
       "events": ["knowledge.document.indexed", "knowledge.document.partial", "knowledge.document.failed"]}'

export SYNAPSE_WEBHOOK_SECRET=whsec_...

2. Receive a delivery

Every delivery has the same envelope, signed with the endpoint's secret:

POST /hooks/synapse HTTP/1.1
Content-Type: application/json
User-Agent: Synapse-Webhook/1.0
X-Synapse-Timestamp: 1759571049
X-Synapse-Signature: sha256=5c0d…
X-Synapse-Signature-V2: sha256=9f1e…

{"id": "kev_…", "type": "knowledge.document.indexed", "created_at": "2026-10-04T09:44:09Z",
 "data": {"kb_id": "kb_…", "doc_id": "kdoc_…", "path": "_records/inv-1039.json",
          "status": "indexed", "previous_status": "indexing", "status_reason": null, …}}

A document's data says which base and document, its new and previous status and why, its version, what was indexed and what it cost. A receiver does three things before anything else:

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["SYNAPSE_WEBHOOK_SECRET"].encode()
seen = set()  # the event ids already handled: keep them in your database


@app.post("/hooks/synapse")
def synapse_event():
    body = request.get_data()  # the raw bytes, before any parsing
    timestamp = request.headers.get("X-Synapse-Timestamp", "0")
    if abs(time.time() - int(timestamp)) > 300:  # older than five minutes
        abort(401)
    signed = timestamp.encode() + b"." + body
    expected = "sha256=" + hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Synapse-Signature-V2", "")):
        abort(401)
    event = request.get_json()
    if event["id"] in seen:  # delivered twice: already handled
        return "", 204
    seen.add(event["id"])
    if event["type"] == "knowledge.document.failed":
        notify_accounts(event["data"]["path"], event["data"]["status_reason"])  # your own code
    return "", 204

1. Verify the signature. X-Synapse-Signature-V2 is sha256= and the hex HMAC-SHA256 of "{X-Synapse-Timestamp}.{body}", keyed with the secret, so it covers when the delivery was sent: refuse a timestamp more than five minutes from your clock. Compute it over the bytes you received, before parsing them, and compare in constant time. (X-Synapse-Signature, over the body alone, is kept for older receivers.)
2. Drop repeats. Delivery is at least once, so an event can arrive twice; its id is the same each time.
3. Answer quickly. Any 2xx is a delivery. Do slow work afterwards, off the request.

Webhooks → Verifying it has the same check in JavaScript.

3. Test it, then watch it work

curl -X POST https://api.synapseorch.com/api/v1/webhooks/{id}/test \
  -H "Authorization: Bearer $SYNAPSE_API_KEY"

curl https://api.synapseorch.com/api/v1/webhooks/{id}/deliveries \
  -H "Authorization: Bearer $SYNAPSE_API_KEY"

4. When deliveries fail

• Retries. A 5xx, 408 or 429, a timeout or a connection failure is tried again after 10 seconds, a minute, 5 minutes and 30 minutes — five attempts in all. Any other 4xx fails the delivery at once, so answer 401 only to a bad signature.
• Redeliver. POST /api/v1/webhooks/{id}/deliveries/{delivery_id}/redeliver sends one again, with the same body and event id.
• Switched off. An endpoint whose deliveries fail 20 times in a row, over more than a day, is switched off, and the workspace's owners and admins hear Webhook switched off in the bell and by email. Once your receiver answers again, switch it back on with PATCH /api/v1/webhooks/{id} and {"active": true}. While it is off, Test and Redeliver are refused.
• Best effort. In rare cases — a server stopping at the wrong moment — an event is never sent. When you must have every document's final state, read it: GET /api/v1/knowledge/documents/{doc_id}.

Go further

• Webhooks — every route, the envelope, verifying in JavaScript, the delivery log
• Knowledge API — records, uploads and documents from your own code
• Notifications — Webhook switched off and the other events people hear about
• The public API — runs, their status and the per-run webhook_url