Webhook Signing Policy

​

Credentials

​

Request

POST <webhook URL>

​

Signing procedure

1. Serialize the request body: Convert the JSON body into a string and retain the exact bytes.
2. Generate the timestamp: Get the current Unix timestamp in seconds (ts).
3. Construct the signed message: Combine the timestamp, a period (.), and the raw request body.
   <ts>.<body>
   
4. Generate the HMAC: Compute HMAC-SHA256 using the signed message and the complete signing secret, including the whsec_ prefix, as the UTF-8 key.
5. Format the signature: Convert the HMAC digest into lowercase hexadecimal.
6. Send the request: Include the timestamp and signature in the request headers. Ensure the request body contains the exact bytes used to generate the signature.
   X-Zuper-Timestamp: <ts>
   X-Zuper-Signature: sha256=<hex>
   

​

Worked example

secret      whsec_testsecret123
ts          1792597200
body        {"invoice_uid":"abc"}
signed      1792597200.{"invoice_uid":"abc"}
signature   sha256=<hex of HMAC-SHA256(secret, signed)>

​

Rules

• Request body: Send the exact bytes used to generate the signature. Re-serializing the JSON body, including changing the key order, spacing, or formatting, returns 401 invalid_signature.
• Signing secret: Use the complete signing secret, including the whsec_ prefix, as the HMAC key. Removing the prefix or Base64-decoding the secret returns 401 invalid_signature.
• Timestamp validity: The timestamp must be within 300 seconds (5 minutes) of the server’s current time. Timestamps outside this window, including those caused by clock differences, return 401 stale_timestamp.
• Timestamp format: Send the timestamp as a plain integer in seconds. Milliseconds, leading zeros, or decimal values return 401 stale_timestamp.
• Content type: Set Content-Type to application/json. Other content types leave the request body unread and cause signature validation to fail.
• Retries: Generate a fresh timestamp and signature for every retry. Requests replayed after 300 seconds are rejected.
• Secret security: Do not expose the signing secret in client-side code or application logs. Anyone with the secret can initiate agent runs.
• Duplicate requests: Accepted requests are not automatically deduplicated. Each accepted request starts a new agent run.
• Secret regeneration: Update callers immediately after regenerating the signing secret. The previous secret becomes invalid at once.

​

Responses

​

Examples

SECRET='whsec_...'
URL='https://<region-host>/api/agent-builder/webhooks/agents/<token>'
BODY='{"invoice_uid":"abc","note":"overdue"}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')

curl -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H "X-Zuper-Timestamp: $TS" \
  -H "X-Zuper-Signature: sha256=$SIG" \
  --data-raw "$BODY"

import crypto from 'node:crypto'

const secret = process.env.ZUPER_WEBHOOK_SECRET
const url = process.env.ZUPER_WEBHOOK_URL
const body = JSON.stringify({ invoice_uid: 'abc', note: 'overdue' })
const ts = String(Math.floor(Date.now() / 1000))
const sig = crypto.createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex')

const res = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Zuper-Timestamp': ts,
    'X-Zuper-Signature': `sha256=${sig}`,
  },
  body,
})

console.log(res.status, await res.json())

import hashlib, hmac, json, os, time
import requests

secret = os.environ["ZUPER_WEBHOOK_SECRET"]
url = os.environ["ZUPER_WEBHOOK_URL"]
body = json.dumps({"invoice_uid": "abc", "note": "overdue"})
ts = str(int(time.time()))
sig = hmac.new(secret.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()

res = requests.post(
    url,
    data=body.encode(),  # Send the signed bytes; do not use json=
    headers={
        "Content-Type": "application/json",
        "X-Zuper-Timestamp": ts,
        "X-Zuper-Signature": f"sha256={sig}",
    },
)

print(res.status_code, res.json())