Webhook Signatures
HMAC-SHA256 per-user signing with v1= format.
Overview
Every webhook delivery is signed with your per-user webhook secret using HMAC-SHA256. This lets you verify that webhooks are from CueAPI, not from a malicious third party.
Signature format
X-CueAPI-Signature: v1=a1b2c3d4e5f6...
X-CueAPI-Timestamp: 1710340800
The signature uses the v1= prefix (Stripe-style) followed by the HMAC-SHA256 hex digest.
How signatures are computed
- Timestamp: Unix epoch seconds (current time when signature is created)
- Signed content:
"{timestamp}.{json_payload_sorted_keys}" - Algorithm: HMAC-SHA256 using your
webhook_secret - Output:
v1={hex_digest}
python
signed_content = f"{timestamp}.{json.dumps(payload, sort_keys=True)}"
signature = hmac.new(secret, signed_content, sha256).hexdigest()
header = f"v1={signature}"Per-user secrets
Each user has their own webhook secret (format: whsec_ + 64 hex characters). Compromising one user's secret does not affect other users.
Webhook headers
| Header | Description |
|---|---|
X-CueAPI-Signature | v1={hmac_sha256_hex} |
X-CueAPI-Timestamp | Unix epoch when signature was created |
X-CueAPI-Cue-Id | The cue that triggered this execution |
X-CueAPI-Execution-Id | Unique execution identifier |
X-CueAPI-Scheduled-For | When this execution was scheduled |
X-CueAPI-Attempt | Attempt number (1 = first try) |
Verification
See the complete Signature Verification Guide with Python and Node.js examples.