Call Lens
Webhooks

Rotating secrets

There is no overlap window. Order matters.

curl -X POST https://api.calllens.io/api/v1/ingest/webhooks/{id}/secret \
  -H "Authorization: Bearer clk_..."

Returns the endpoint plus the new secret.

There is no overlap window. The next delivery is signed with the new secret only. The old secret stops working the instant you rotate.

Rotating without dropping deliveries

Because there is no dual-signing period, the safe pattern is to make your consumer accept either secret across the change:

  1. Deploy a consumer that tries the current secret, then a CALLLENS_WEBHOOK_SECRET_NEXT value if the first fails. With no next value configured it behaves exactly as before.
  2. Rotate. Store the returned secret as CALLLENS_WEBHOOK_SECRET_NEXT.
  3. Confirm with POST /webhooks/{id}/test — the probe is signed with the new secret.
  4. Promote the new value to CALLLENS_WEBHOOK_SECRET and clear the next value.

Trying two secrets means two constant-time comparisons; it does not weaken verification.

If you have lost the secret

Rotate. There is no way to read an existing secret — POST /webhooks returned it once and no route returns it again.

Retries and failures

What happens when your endpoint does not answer.

Errors

Every code Call Lens can refuse with, and what a client should do about each.

On this page

Rotating without dropping deliveriesIf you have lost the secret