Skip to main content

Signing Secrets API

Generate and rotate HMAC signing secrets for webhook signature verification.

Generate a signing secret​

Creates an initial signing secret for the organization. Use this if no signing secret exists yet.

POST /api/v1/organizations/:id/signing_secret
curl -X POST https://app.hooklistener.com/api/v1/organizations/org_abc123/signing_secret \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "signing_secret": "whsec_a1b2c3d4e5f6...",
  "created_at": "2025-01-15T10:00:00Z"
}

Roll (rotate) the signing secret​

Generates a new signing secret, replacing the previous one. The old secret immediately stops being valid.

POST /api/v1/organizations/:id/signing_secret/roll
curl -X POST https://app.hooklistener.com/api/v1/organizations/org_abc123/signing_secret/roll \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "signing_secret": "whsec_new_secret_value...",
  "created_at": "2025-01-15T12:00:00Z"
}

What are signing secrets?​

Signing secrets let you verify that webhooks forwarded by Hooklistener are authentic and haven't been tampered with. When Hooklistener forwards a request, it can include an HMAC signature in the headers that you verify using your signing secret.

See Platform: Signing Secrets for verification examples.