---
title: "Create a new SharedKey"
method: POST
path: "/v1/Webhooks/SharedKeys"
tags: ["SharedKeys"]
---

# Create a new SharedKey

`POST /v1/Webhooks/SharedKeys`

## Request

- Base URL: `https://webhooks.twilio.com`
- URL: `https://webhooks.twilio.com/v1/Webhooks/SharedKeys`
- Auth: HTTP basic

Creates a new Shared Key for webhook signature validation.

**IMPORTANT**: The `secret` field is ONLY returned in this response and cannot be retrieved later.
Store it securely in your secrets management system.

## Headers

- `Idempotency-Key` string, uuid

## Request body

- PostSharedKey: Request body for creating a new SharedKey
  - `friendlyName` string, nullable: Human-readable name for the signing key (optional, defaults to blank)

## Response `201`

SharedKey created (secret included only in this response)

- SharedKeyWithSecret
  - `id` string, required: Unique SharedKey identifier (TypeID/TTID format)
  - `friendlyName` string, required: Human-readable name for identification
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `secret` string, required: Signing secret (only returned on POST, cannot be retrieved later)

## Other responses

- `400`: Validation error (friendlyName exceeds maximum length). friendlyName itself is optional and defaults to blank.
- `401`: Authentication failed
- `403`: Authenticated account does not have permission to perform this operation
- `422`: Account has reached maximum SharedKeys limit
- `429`: Rate limit exceeded
- `500`: An unexpected server error occurred

---

[API](https://skmtc.dev/twilio/apis/webhooks-v1.md) - [All operations](https://skmtc.dev/twilio/apis/webhooks-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/twilio/apis/webhooks-v1/revisions/629b4cc3a029?raw)
