Webhooks¶
A webhook tells your server the moment something happens in a workspace: a share was revoked, a request was answered, a member left. You register an address once, pick the events it should hear, and every event is POSTed to it, signed, retried until it lands, and logged so you can see and resend what was sent.
Webhooks belong to a workspace, not to a single request. The older per-request callback URL keeps working and is unaffected; for new integrations, use webhooks.
Example: a share-revocation notification¶
The following commands register an HTTPS receiver for link.revoked and send
a test delivery. Prerequisites: a running receiver, its public URL, and an API
key with webhook:manage in the workspace being monitored.
SERVER='https://api.example.com'
RECEIVER_URL='https://service.example.com/hooks/revoked'
read -r -s -p 'API key: ' REVOKED_API_KEY
printf '\n'
curl --fail-with-body "$SERVER/api/webhooks/endpoints" \
-H "X-API-Key: $REVOKED_API_KEY" \
-H 'Content-Type: application/json' \
-d "{\"url\":\"$RECEIVER_URL\",\"events\":[\"link.revoked\"]}"
The creation response includes the endpoint ID and signing secret. The
receiver uses that secret to verify deliveries.
With the returned endpoint ID:
ENDPOINT_ID='REPLACE_WITH_RETURNED_ID'
curl --fail-with-body -X POST \
"$SERVER/api/webhooks/endpoints/$ENDPOINT_ID/test" \
-H "X-API-Key: $REVOKED_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"link.revoked"}'
The receiver should get a signed event with "test": true. A successful test
checks delivery and signature handling; test IDs are placeholders and cannot
be used to fetch real objects. Revoking a real share later sends a normal
link.revoked event with that share's ID. A blocked or unreachable receiver is
described in the returned delivery result.
For local development, the bundled receiver avoids writing a listener first. Private destinations require the server setting described under Delivery.
What an event carries¶
An event names what changed and its new state. It never carries a value: no record values, no answers, no labels, no share slugs. Your server reads what it needs through the API with an API key, where a revoked share or answer simply stops answering. That keeps sealed records sealed and keeps secrets out of the logs on both sides.
{
"id": "q8m2k4x7p1zvwy3",
"type": "link.revoked",
"created": "2026-11-03T09:14:03Z",
"workspace": "lxt7nlkvfqairg5",
"data": {
"object": "link",
"id": "9k2m4pqx81zvwy3",
"status": "revoked",
"kind": "share"
}
}
| Field | Meaning |
|---|---|
id |
The event's id. Every delivery and resend of the event carries the same id, so use it to drop duplicates. |
type |
One of the event types. |
created |
When it happened. |
workspace |
The workspace it happened in. |
data |
object and id name what changed; the other fields depend on the type. |
test |
Present and true only on a test event. |
Event types¶
GET /api/webhooks/event-types serves this list, so a client never has to
hard-code it.
| Type | Sent when | data |
|---|---|---|
link.created |
A share was created, or an answer was given from this workspace. | id, status, kind (share or answer), request for an answer |
link.updated |
A share's records, limits or label changed. | as above |
link.viewed ¹ |
Someone opened a share. | as above, plus views |
link.paused / link.resumed |
A share was paused, or turned back on. | as above |
link.revoked |
A share was revoked or deleted. | as above, deleted: true if deleted |
link.expired |
A share reached its end date or its view limit. | as above, reason: "max_views" for the limit |
request.created |
A request was created. | id, status |
request.paused / request.resumed |
A request was paused, or turned back on. | id, status |
request.closed |
A request was revoked, expired, completed or deleted. | id, status, deleted: true if deleted |
response.submitted |
Someone answered one of this workspace's requests. | id (the answer), request, status, server for an answer kept on another server |
response.changed |
An answer's entries changed, it was answered again, paused or resumed. | as above |
response.revoked |
The responder took their answer back. | as above |
response.expired |
An answer reached its end date or view limit. | as above |
record.created / record.deleted |
A vault record was added or deleted. | id, key |
record.updated ¹ |
A vault record changed. | id, key |
attestation.issued / attestation.revoked |
An attestation was accepted, or revoked. | id, type, status |
identity.created / identity.revoked |
An identity was created, or revoked. | id, fingerprint, status |
member.joined / member.updated / member.removed |
Someone joined, their permissions changed, or they left. | id, user, permissions |
apikey.created / apikey.revoked |
An API key was created or deleted. | id, user |
connection.approved / connection.revoked |
A tool was connected or removed. | id, clientId |
¹ Frequent. An endpoint subscribed to "*" gets every type except these
two; name them to receive them.
response.* goes to the workspace that asked. The answer itself lives in
the responder's workspace, which sees it as link.* with kind: "answer".
Events are recorded only while the workspace has an enabled endpoint that subscribes to them. Nothing is collected for a workspace with no webhooks.
Delivery¶
POST,Content-Type: application/json,User-Agent: Revoked-Webhooks/1.- Headers:
Revoked-Event-Id,Revoked-Event-Type,Revoked-Signature. - Each attempt has 10 seconds. Redirects are not followed.
- Any
2xxis delivered. Anything else, or no answer, is retried: after 30 seconds, then doubling up to six hours, 12 tries over about a day and a half. Answer quickly and do the work afterwards. - A delivery can therefore arrive more than once and out of order. Drop
repeats by
id; order bycreated. - An endpoint that has failed for three days without a single success is turned off, and whoever created it gets a notification. Turn it back on and replay what it missed.
The address policy is the one callbacks use: an absolute http/https URL,
loopback and private ranges refused unless the server runs with
ALLOW_PRIVATE_CALLBACKS=true, the resolved address re-checked at connect
time. See Callbacks → Security.
On a server without ALLOW_PRIVATE_CALLBACKS, an endpoint at a loopback or
private address is refused when it is saved, and a test sent to one fails as
blocked. The app says so under the address as soon as one is typed, and on
the page of an existing endpoint at such an address, since nothing will ever
arrive there. GET /api/webhooks/event-types answers privateCallbacks, so a
client can do the same.
Verifying the signature¶
Every delivery carries
Revoked-Signature: t=1793704443,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
v1 is the hex HMAC-SHA256, keyed with the endpoint's signing secret, of the
timestamp, a full stop, and the raw request body: "{t}.{body}". Check it
against the bytes you received, before parsing them, and refuse a timestamp
more than five minutes old so a captured delivery cannot be replayed.
import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool:
parts = [p.split("=", 1) for p in header.split(",")]
t = next(v for k, v in parts if k == "t")
if abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, v) for k, v in parts if k == "v1")
After a rotation the header carries two v1 values, one per
secret, for 24 hours. Accept a match against either.
Endpoints¶
All routes are under /api/webhooks, take a session or an API key, and need
the Manage webhooks permission (webhook:manage on a key). Every route
acts on the caller's active workspace (a key's own workspace); another
workspace's webhooks answer 404.
| Route | Does |
|---|---|
GET /event-types |
The event catalogue. |
GET /endpoints |
Your endpoints, each with the last day's stats. |
POST /endpoints |
Create one: url, optional description, events (defaults to ["*"]). The answer holds the secret. |
GET /endpoints/{id} |
One endpoint. |
PATCH /endpoints/{id} |
Change url, description, events, or enabled. |
DELETE /endpoints/{id} |
Delete it and its log. |
GET /endpoints/{id}/secret |
The current signing secret. |
POST /endpoints/{id}/rotate-secret |
A new secret; the old one keeps signing for 24 hours. |
POST /endpoints/{id}/test |
Send a sample type now; answers with the delivery. |
POST /endpoints/{id}/replay |
Queue every failed delivery since since (RFC 3339, default 24 hours ago) again. |
GET /events?type= |
The event log, newest first. |
GET /deliveries?endpoint=&status=&type=&event= |
The delivery log, newest first. status is pending, succeeded or failed. |
GET /deliveries/{id} |
One delivery: its payload and every attempt (attemptLog), with the status, the first 2 KB of what your server answered, and how long it took. |
POST /deliveries/{id}/resend |
Try it again now. A resend that lands marks it delivered; one that fails leaves the automatic retries as they were. |
Lists take page and perPage (at most 100). A workspace holds up to 16
endpoints. Creating, changing and deleting an endpoint is written to the audit
log; the secret never is.
Resending¶
Every delivery is kept for 30 days, with its payload and every attempt. In the app, open Settings → Webhooks → your endpoint, tap a delivery, and Resend. Resend failed on the endpoint's page queues everything that failed in the last day, which is what you want after fixing your server.
Testing¶
Send test on an endpoint's page, or POST /endpoints/{id}/test, sends one
sample of the type you pick through the real path: the same signature, the
same client, the same address policy. The sample's ids start with example_
and the body carries "test": true. A test is tried once and never retried.
To watch deliveries on your own machine, run
examples/webhook_receiver.py.
It listens on 127.0.0.1:47381, checks the signature when
REVOKED_WEBHOOK_SECRET holds the endpoint's secret, drops repeats, and
prints each event with a link to what it carries. A local server must run
with ALLOW_PRIVATE_CALLBACKS=true to deliver to it.
Errors¶
code |
Means |
|---|---|
webhook_url_invalid |
Not an absolute http/https URL, or one the address policy refuses. |
webhook_events_invalid |
No events, or a name that is not in the catalogue. |
webhook_limit_reached |
The workspace already has 16 endpoints. |
webhook_not_found / webhook_delivery_not_found |
Not in your workspace. |
webhook_disabled |
Replay on an endpoint that is turned off. |
missing_permission |
You or the key lack Manage webhooks. |