HMAC-SHA256, headers, signed payload shape, and time window).
If you only need the URL and fire path without signatures, start with Webhooks.
When HMAC applies
On a Webhook Source node you choose authentication:
Save the pipeline (auto-save counts) after you switch to HMAC Signature. The UI then shows the signing secret for that source. Treat the URL path token and the signing secret as secrets.
Older webhook triggers that use a UUID URL (not
/api/webhooks/source/…) always require HMAC when a secret is configured. This page documents the same signature format for both paths.Contract summary
Mint the URL and secret
1
Add a Webhook Source node
On the pipeline canvas, add a Webhook Source node. Set Allowed method (
POST, PUT, or PATCH) and Authentication to HMAC Signature.2
Save the pipeline
Save or wait for auto-save. Planasonix provisions a linked trigger and fills Your Webhook URL with an absolute URL of the form:
https://<your-app-host>/api/webhooks/source/<ingest-token>3
Copy the signing secret
With HMAC enabled, copy Signing secret from the node config. Store it in your sender’s secret manager. Re-save after rotating auth settings so the UI and trigger stay in sync.
Build the signature
- Read the raw body bytes you will send (or empty bytes for no body).
- Set
timestampto the current Unix time in seconds (string form, for example1712345678). - Build the signed string:
- Non-empty body:
timestamp + "." + bodyas UTF-8 - Empty body:
timestamponly
- Non-empty body:
- Compute
HMAC-SHA256(key=secret_utf8_bytes, message=signed_string). - Hex-encode the digest (lowercase).
- Set headers:
X-Planasonix-Timestamp: <timestamp>X-Planasonix-Signature: v1=<hex>
Clock skew
- Timestamps older than 300 seconds are rejected (
signature expired). - Timestamps more than 60 seconds in the future are rejected (
clock skew detected). - Sync sender clocks with NTP. If your worker buffers jobs, sign at send time—not at enqueue time.
Examples
ReplaceWEBHOOK_URL and SIGNING_SECRET with values from the node config.
"Webhook processed"). Planasonix then runs the pipeline asynchronously.
Status codes
Common failures
Related topics
Webhooks
Mint the URL, choose method/auth, and fire a pipeline.
Triggers
Event-based alternatives (S3, GCS, Azure, file watcher).