Skip to main content
Phala Cloud sends HTTP POST requests to your endpoint when events occur in your workspace — CVM deployments, updates, stops, deletes, and multisig approval requests. Each request includes an HMAC-SHA256 signature for verification.

Supported Events

Payload Format

For failure events, data includes an error field:

HTTP Headers

Verifying Signatures

Each webhook has a signing secret (starts with whsec_). Use it to verify requests are authentic and untampered. The signature is: sha256=HMAC-SHA256(secret, "{timestamp}.{raw_body}") The Phala Cloud SDKs provide built-in verification with timestamp tolerance checks and constant-time comparison.
All three SDKs automatically reject timestamps older than 5 minutes (configurable via toleranceSeconds) and use constant-time comparison to prevent timing attacks.
Replay protection: reject events where 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/webhooks response
  • Masked afterward — subsequent GET/LIST responses 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

Returns the full signing secret. Requires:
  • Account with 2FA enabled (returns 403 if not)
  • Recent 2FA step-up verification (returns 428 if not verified)

Rotate Secret

Generates a new signing secret and invalidates the previous one. Same 2FA requirements as reveal.
After rotation, update your webhook consumer with the new secret immediately. Events signed with the old secret will fail verification.

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/16 including 169.254.169.254 (cloud metadata)
    • ::1, fc00::/7, fe80::/10 (IPv6 private/loopback)
  • No localhostlocalhost and .local domains are not allowed
These restrictions apply both at webhook creation and at delivery time to prevent DNS rebinding attacks.

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-Signature before processing
  • Respond fast — return 200 immediately, process asynchronously (10s timeout)
  • Be idempotent — use the id field to deduplicate retries
  • Check timestamps — reject events older than 5 minutes