Skip to main content
Use this page when your sender must sign requests to a Planasonix Webhook Source URL. The contract below matches the production verifier (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

  1. Read the raw body bytes you will send (or empty bytes for no body).
  2. Set timestamp to the current Unix time in seconds (string form, for example 1712345678).
  3. Build the signed string:
    • Non-empty body: timestamp + "." + body as UTF-8
    • Empty body: timestamp only
  4. Compute HMAC-SHA256(key=secret_utf8_bytes, message=signed_string).
  5. Hex-encode the digest (lowercase).
  6. Set headers:
    • X-Planasonix-Timestamp: <timestamp>
    • X-Planasonix-Signature: v1=<hex>
Sign the byte-identical body you transmit. Pretty-printing JSON, changing key order, adding a trailing newline, or re-serializing after parse produces a different digest and 401. Prefer signing the exact buffer you write to the socket.

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

Replace WEBHOOK_URL and SIGNING_SECRET with values from the node config.
Successful ingest returns 200 with a short JSON acknowledgement (for example "Webhook processed"). Planasonix then runs the pipeline asynchronously.

Status codes

Common failures

Webhooks

Mint the URL, choose method/auth, and fire a pipeline.

Triggers

Event-based alternatives (S3, GCS, Azure, file watcher).