Secret rotation

Your webhook subscription has its own signing secret, separate from the client_secret you use to get a token. The two are rotated differently, and the difference matters: an API credential rotation has a grace period, a webhook secret rotation does not.

How the secret is issued

The secret is a 64-character hex string generated by BankCore when the bank creates your subscription. It is returned to the bank operator once, in the create response, and never again: no endpoint reads it back, and the partner portal does not show it in any form. Your relationship manager hands it to you out of band. Store it in your secret manager at that moment.

Use the secret’s characters as the HMAC key, not its hex-decoded bytes. See Verifying signatures.

Rotation is immediate

Rotation is a staff action on the bank’s side, requested through your relationship manager. When the bank rotates, BankCore generates a new secret and starts using it at once:

• the moment the rotation is saved, every subsequent delivery is signed with the new secret,
• that includes retries of deliveries queued before the rotation, because each attempt is signed afresh at send time,
• the old secret is not accepted for anything. There is no overlap period.

Rotation does not pause delivery. If your endpoint is still verifying against the old secret, every delivery from that moment is a signature failure on your side. If you answer those with a 401, each one is recorded as rejected and is not retried.

Not the same as client_secret rotation

Your API client_secret keeps working for a grace period after rotation so you can roll it out without downtime. The webhook signing secret has no such grace period. Do not assume one.

Rotating without losing events

Because the cutover is instant, the overlap has to live on your side. Accept both secrets while you change over.

1. Deploy a verifier that accepts either secret. Compute the expected digest for the new secret and for the old one and accept the request if either matches, each comparison in constant time:

   $valid = hash_equals($expected_new, $received) || hash_equals($expected_old, $received);

   Until the bank rotates, the new slot is empty and only the old secret verifies.

2. Ask the bank to rotate. Your relationship manager runs the rotation and sends you the new secret out of band. Load it into the new slot.

3. Confirm traffic is verifying against the new secret. Log which slot matched. Once every delivery matches the new one, and the retry ladder for anything queued before the rotation has drained, remove the old secret.

4. Replay if anything slipped. If deliveries were rejected between the rotation and your reload, ask the bank to replay that window to your subscription. Replays carry the original body under a new X-Webhook-Id; see Delivery and retries.

If a secret has leaked

Rotate immediately and accept the event loss, then ask for a replay of the window. Between the leak and the rotation, treat any webhook you cannot otherwise corroborate (by the statement, by a check-payment call) as suspect. A webhook is a notification, not the ledger; the statement is.

Rotating the subscription URL

Changing the endpoint URL is also a staff action and is independent of the secret: the URL changes, the secret does not, and queued deliveries go to the new URL on their next attempt. Deliveries already in the retry ladder are re-checked against the subscription at each attempt, so a subscription that is disabled or has an event type removed stops those deliveries rather than finishing the ladder.

In the portal

The API access page shows your API client and its status; Webhook endpoints shows each subscription’s URL and event types. Neither shows a secret, and neither offers rotation: both are requested through the bank.