Secrets API

Store and retrieve encrypted key-value secrets for your organization.

List secrets

GET /api/v1/secrets

curl https://app.hooklistener.com/api/v1/secrets \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "data": [
    {
      "id": "sec_abc123",
      "name": "STRIPE_WEBHOOK_SECRET",
      "inserted_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Secret values are never included in list responses.

Create a secret

POST /api/v1/secrets

curl -X POST https://app.hooklistener.com/api/v1/secrets \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": {
      "name": "STRIPE_WEBHOOK_SECRET",
      "value": "whsec_a1b2c3d4..."
    }
  }'

Request body:

Field	Type	Required	Description
name	string	Yes	Secret name, must match ^[A-Z][A-Z0-9_]*$ (unique within org)
value	string	Yes	Secret value (encrypted at rest, max 10,000 chars)
description	string	No	Optional description (max 1,000 chars)

Response: 201 Created

Get a secret

GET /api/v1/secrets/:id

Returns secret metadata without the value.

Get a secret's value (decrypt)

GET /api/v1/secrets/:id/value

curl https://app.hooklistener.com/api/v1/secrets/sec_abc123/value \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "id": "sec_abc123",
  "name": "STRIPE_WEBHOOK_SECRET",
  "value": "whsec_a1b2c3d4...",
  "decrypted_at": "2025-01-15T11:00:00Z"
}

Update a secret

PUT /api/v1/secrets/:id

curl -X PUT https://app.hooklistener.com/api/v1/secrets/sec_abc123 \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": {
      "name": "STRIPE_WEBHOOK_SECRET",
      "value": "whsec_new_value..."
    }
  }'

Delete a secret

DELETE /api/v1/secrets/:id

curl -X DELETE https://app.hooklistener.com/api/v1/secrets/sec_abc123 \
  -H "Authorization: Bearer hklst_your_api_key"

Response: 204 No Content