Rotate a webhook signing secret

Rotate a compliance-provider webhook signing secret when the current secret may be exposed, when a scheduled key-rotation policy comes due, or when you move a provider integration to new credentials. The Platform API stages the new secret first, keeps the old one valid for a grace window, and activates the new one only when you promote it. Both secrets verify inbound events during the window, so events the provider already queued under the old secret are not lost.

For the provider record, claim topics, and first webhook, see Onboard a compliance provider. For the full endpoint and field reference, see Compliance provider API reference.

Prerequisites

• API access for a user with the admin, systemManager, or complianceManager role on the active organisation.
• An active compliance provider with at least one webhook. New providers and topics are created through provider onboarding.
• The provider ID from the Console provider detail page or the provider list endpoint.
• A new signing secret value, and access to the provider dashboard where the inbound webhook secret is configured.

How staged rotation works

Rotation has three operations. Each one acts on the webhook for the provider you name.

During the grace window, DALP verifies an inbound webhook against either the active secret or the pending secret. This overlap is what lets you change the secret in the provider dashboard without dropping events that the provider signed with the old secret moments before the change.

A webhook holds one pending rotation at a time. Promote or cancel the current pending secret before you start another rotation.

This guide rotates the provider's primary webhook secret, which is the secret tied to the provider ID you pass to these endpoints. A provider that serves more than one claim topic keeps a separate webhook secret per topic. Rotate one provider record at a time, and confirm each rotation against the provider record it returns.

curl -X POST "https://your-platform.example.com/api/v2/compliance/providers/44444444-4444-4444-4444-444444444444/rotate-secret" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookSigningSecret": "new-provider-signing-secret",
    "graceWindowMinutes": 30
  }'

curl -X POST "https://your-platform.example.com/api/v2/compliance/providers/44444444-4444-4444-4444-444444444444/promote-secret" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Cancel a rotation

Cancel a pending rotation when you started one in error, used the wrong secret value, or no longer want to change the secret. Cancelling discards the pending secret and leaves the active secret in place.

curl -X POST "https://your-platform.example.com/api/v2/compliance/providers/44444444-4444-4444-4444-444444444444/cancel-secret-rotation" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

After cancellation, the webhook has no pending rotation, so you can start a fresh one. If you already changed the secret in the provider dashboard, change it back to the active value, because the discarded pending secret no longer verifies events.

Errors

Concurrent rotation is safe by design. If two sessions try to act on the same pending secret, only one succeeds; the other receives DALP-0501 so it can refresh and re-decide rather than reverting the secret to a stale value.

See also

• Onboard a compliance provider
• Compliance provider API reference
• How compliance provider intake works
• Platform API error reference