Secrets

Register where events are delivered, roll the signing secret without dropping a delivery, and see how the destination is behaving.

Add a signing secret

POST/v1/webhook_endpoints/{endpoint}/secrets

Retire a signing secret

DELETE/v1/webhook_endpoints/{endpoint}/secrets/{secret}

List signing secrets

GET/v1/webhook_endpoints/{endpoint}/secrets

ModelsExpand Collapse

SigningSecret object { id, created_at, retired_at, status }

One signing secret. Every ACTIVE secret signs every event, and all of the signatures ride the one webhook-signature header — which is what makes a rotation lossless.

id: string

The secret’s id. Safe to log: it is a handle, not key material.

created_at: string

formatdate-time

retired_at: string

When this secret stopped signing. null while it is active.

formatdate-time

status: string

active or retired. Values grow additively.

SigningSecretCreated object { id, created_at, retired_at, 2 more }

A newly added signing secret, with its value — shown exactly once.

id: string

The secret’s id. Safe to log: it is a handle, not key material.

created_at: string

formatdate-time

retired_at: string

When this secret stopped signing. null while it is active.

formatdate-time

secret: string

The signing secret in presentation form (whsec_ + base64). Shown exactly once, here.

status: string

active or retired. Values grow additively.

SigningSecretList object { data }

An endpoint’s signing secrets, oldest first — the order they sign in.

data: array of SigningSecret { id, created_at, retired_at, status }

id: string

The secret’s id. Safe to log: it is a handle, not key material.

created_at: string

formatdate-time

retired_at: string

When this secret stopped signing. null while it is active.

formatdate-time

status: string

active or retired. Values grow additively.