Which Sume key scope reads or rotates the webhook signing secret?

GET /v1/webhooks/signing-secret needs a key with the account:read scope, and POST /v1/webhooks/signing-secret/rotate needs account:write. Sume fixes a key's scopes when you create it and has no call to add one later. If your deploy key lacks the scope, make a new key for the job rather than widening the one your app uses at runtime.

Scope per call

The old secret keeps verifying for 24 hours after a rotation. During that window every delivery carries two signatures in x-sume-webhook-signature, newest first, and a verifier that holds either secret passes.

A deploy script that prints no secret

The script reads the fingerprint and prints it. The fingerprint matches x-sume-webhook-secret-fingerprint on deliveries, so you can compare both sides without quoting the secret. Pass rotate as the first argument to rotate, which prints the new fingerprint and the time the old secret stops working. It does not print either secret; install the new one from your secret store.

#!/usr/bin/env bash
set -euo pipefail
: "${SUME_API_KEY:?set SUME_API_KEY}"   # needs account:read, and account:write to rotate
H="x-api-key: $SUME_API_KEY"
B=https://api.sume.com/v1/webhooks/signing-secret

# Read: print only the fingerprint, never the secret.
curl -sf -H "$H" "$B" | jq -r '"fingerprint " + .data.fingerprint'

if [ "${1:-}" = "rotate" ]; then
  # Rotate: the old secret keeps verifying for 24 hours.
  curl -sf -X POST -H "$H" "$B/rotate" |
    jq -r '"new fingerprint " + .data.fingerprint,
           "old secret valid until " + .data.rotation.previous_valid_until'
fi

Keep the keys apart

• Use one key for runtime calls such as submits and polls, and a second key with account scopes that only your deploy pipeline can read.
• A key made before a scope existed does not have it. A call without the needed scope fails with 403 insufficient_scope.
• Rotate on a schedule you control, and install the new secret before the previous_valid_until time in the response.
• Send one credential header only. Sending both Authorization and x-api-key gives a 401.

Where the secret goes

The secret is 64 hex characters, and Sume signs both job webhooks and run webhooks with the same one for a workspace. Two members of one team share a verifier, which is what a team integration expects. Put it in your secret manager under SUME_COM_WEBHOOK_SIGNING_SECRET, the name the docs use, and make the receiver refuse to start when the value is empty.

If you rotate twice in a row while the first window is still open, the second rotation replaces the window. The secret from two rotations back stops verifying at once, so wait for the first rollout to finish before you start another.