Retrieve the signing secret
GET /v1/webhooks/{webhook_id}/secret
Read as Markdown ↗GET /v1/webhooks/{webhook_id}/secret
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Returns the current signing secret. This is the explicit disclosure path for a secret whose creation response was lost or that another system needs; it never appears in listings, details, history or logs. Treat the response as a credential: do not print it.
After a rotation with overlap, this returns the new secret; the replaced one keeps signing until previous_secret_expires_at on the webhook. Deliveries carry one signature per live secret, so verifying against either succeeds during the overlap.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
webhook_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request GET \
"https://cherami.to/v1/webhooks/WEBHOOK_ID/secret" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"id": "55555555-5555-4555-8555-555555555555",
"secret": "whsec_EXAMPLE_NOT_A_REAL_SECRET"
}HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 503
webhook_secret_unavailable: The signing secret could not be read. If error.details.webhook_id is present the webhook was added; retrieve its secret explicitly.
webhooks_unavailable: Webhook management is unavailable or the operation's outcome is unknown. Read or list webhooks before repeating a change; adding again can create a duplicate.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: WebhookSecret
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
secret | Yes | string | Signing secret for Standard Webhooks verification (whsec_ prefix). Returned on creation, explicit retrieval and rotation only. Store privately. |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1