Webhook Config (self-serve)

Webhook URL or secret rotation does not require an ops channel. A partner can call PUT /external/site/webhook-config with its own API key and update the settings directly. The new secret is returned once in the response; if you do not store it, you must rotate again.

Update webhook config

PUT /api/v1/external/site/webhook-config

New URL + new secret

curl -X PUT "$PIENTEGRA_API_BASE/external/site/webhook-config" \
  -H "Authorization: Bearer $PIENTEGRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.partner.com/pientegra/webhooks",
    "rotateSecret": true
  }'

Response

{
  "webhookUrl": "https://api.partner.com/pientegra/webhooks",
  "webhookSecret": "whsec_NN3hv5lXbE0...",
  "rotatedAt": "2026-04-28T16:00:00.000Z"
}

Body fields

Field	Type	Required	Description
`webhookUrl`	`string` (URL)	Yes	HTTPS endpoint. Pientegra sets this URL as the delivery target.
`rotateSecret`	`boolean`	No	`true` by default: generate a new signing secret and return it in the response. `false`: keep the current secret and update only the URL.

Response fields

Field	Description
`webhookUrl`	Active new URL, echoed back.
`webhookSecret`	`whsec_<32-byte-base64url>`; present only when `rotateSecret=true`, otherwise `null`.
`rotatedAt`	UTC timestamp when the rotation was recorded server-side.

Rotation playbook

To move from the old secret to the new one without downtime, keep a short overlap window in your handler:

Call PUT /external/site/webhook-config and store the new secret.
Verify every incoming webhook with the new secret first, then fall back to the old secret if verification fails.
After Pientegra completes in-flight retries that started with the old secret, remove the old secret from the handler. Worst case: 8 attempts x roughly 5 minutes, around a 10-minute window.

For HMAC verification details, see Webhook Security.

Audit

Each rotation emits a SITE.WEBHOOK_CONFIG_ROTATED audit event. A partner or Pientegra ops can check the Audit Log at any time to see who performed the rotation and when. Event metadata includes rotatedSecret: true|false.