Supported Events
Payload Format
data includes an error field:
HTTP Headers
Verifying Signatures
Each webhook has a signing secret (starts withwhsec_). Use it to verify requests are authentic and untampered.
The signature is: sha256=HMAC-SHA256(secret, "{timestamp}.{raw_body}")
Using SDKs (Recommended)
The Phala Cloud SDKs provide built-in verification with timestamp tolerance checks and constant-time comparison.toleranceSeconds) and use constant-time comparison to prevent timing attacks.
Manual Verification (Python / Node.js)
Manual Verification (Python / Node.js)
X-Webhook-Timestamp is older than 5 minutes.Delivery Behavior
Secret Management
Webhook signing secrets follow a strict security model:- Shown once at creation — the full secret is returned only in the
POST /workspace/webhooksresponse - Masked afterward — subsequent
GET/LISTresponses return a masked value (e.g.whsec_****...xxxx) - Reveal requires 2FA — to view the full secret again, your account must have two-factor authentication enabled and recently verified
- Rotation requires 2FA — generating a new secret also requires 2FA verification
Reveal Secret
- Account with 2FA enabled (returns
403if not) - Recent 2FA step-up verification (returns
428if not verified)
Rotate Secret
URL Requirements
Webhook URLs must meet the following requirements:- HTTPS only — HTTP URLs are rejected
- Public addresses only — URLs resolving to private or reserved IP ranges are blocked:
127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16(private)169.254.0.0/16including169.254.169.254(cloud metadata)::1,fc00::/7,fe80::/10(IPv6 private/loopback)
- No localhost —
localhostand.localdomains are not allowed
Managing Webhooks
Dashboard
Settings → Webhooks in your workspace:- Create, edit, enable/disable, delete webhooks
- Select subscribed events
- Send test events
- View delivery history with stats (success rate, response time)
- Resend failed deliveries
API
Best Practices
- Verify signatures — always check
X-Webhook-Signaturebefore processing - Respond fast — return
200immediately, process asynchronously (10s timeout) - Be idempotent — use the
idfield to deduplicate retries - Check timestamps — reject events older than 5 minutes

