Built · control planeEvents 1.0 · HMAC-SHA256 · mainnet 4663 · testnet 46630
Webhooks
Signed events from PALISEC to your systems. Sent after the response, so a webhook can never delay or change a decision.
Events
operation.allowed,operation.denied,operation.review_required: a new recorded decision (idempotent replays send nothing).approval.approved,approval.rejected: a human decision on a held operation.organization.emergency_stop,agent.status_changed,credential.revoked.security.finding: a new finding from the detectors or the PALISEC Agent.operation.submitted: PALISEC co-signed an operation for a smart account and the bundler accepted it.operation.executed: the operation was included on chain, with its transaction hash and whether it succeeded.ping: sent by Test in the console.
Every operation.* and approval.* event carries chain_id (4663 mainnet, 46630 testnet). One endpoint receives both networks; filter on chain_id so testnet activity never reaches a mainnet system.
Delivery
request
POST https://your-service.example/palisec
content-type: application/json
palisec-event-id: 0d0c6f0e-… # stable across retries: deduplicate on it
palisec-event-type: operation.denied
palisec-timestamp: 1794000000
palisec-signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>
{ "id": "0d0c6f0e-…", "type": "operation.denied", "created_at": "…", "organization_id": "…",
"data": { "operation_id": "…", "request_id": "…", "chain_id": 4663, "decision": "DENY", "reason_code": "PS_TARGET_001", … } }- Up to three attempts with backoff on network errors, 429 and 5xx; each attempt reuses the event ID. Failed deliveries can be sent again from the console, with the same ID.
- Respond with any 2xx within 5 seconds. Redirects are not followed.
- Twenty failed events in a row disable the endpoint until a member re-enables it.
- Only public HTTPS endpoints are accepted: no private, loopback, link-local or metadata addresses.
Verify every delivery
receiver.ts
import { verifyWebhook } from "@palisec/sdk";
// rawBody: the exact request body string, before JSON parsing
const event = await verifyWebhook(process.env.PALISEC_WEBHOOK_SECRET!, rawBody, request.headers);
if (await alreadyHandled(event.id)) return new Response(null, { status: 200 });receiver.py
from palisec import webhooks
event = webhooks.verify(os.environ["PALISEC_WEBHOOK_SECRET"], raw_body, request.headers)
# raises webhooks.WebhookVerificationError if forged, modified or older than 5 minutesBoth reject a body that was modified, a wrong secret, and timestamps older than five minutes, and compare in constant time. The signing secret is shown once, when you create the webhook.