> ## Documentation Index > Fetch the complete documentation index at: https://docs.letmepost.dev/llms.txt > Use this file to discover all available pages before exploring further. # Register a webhook endpoint > Authenticated with an API key or dashboard session. The `signingSecret` is returned **once** at creation and is used to verify the HMAC-SHA256 `X-Letmepost-Signature` header on every delivery. An empty `events` array subscribes to every event type. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/webhook-endpoints openapi: 3.1.0 info: title: letmepost.dev API version: v1 description: >- Open-source social media publishing API. Preflight validation, transparent errors, idempotency, stable platform versions. The full developer documentation lives at [letmepost.dev/docs/](https://letmepost.dev/docs/). This reference is generated from the canonical Zod schemas at `packages/schemas/`. **Auth:** Bearer key in the `Authorization` header. See [Authentication](https://letmepost.dev/docs/authentication/). **Idempotency:** every write accepts `Idempotency-Key`. See [Idempotency](https://letmepost.dev/docs/idempotency/). **Errors:** stable envelope with `code`, `rule`, `platformResponse`, `remediation`, `docUrl`, `ruleUrl`. See [Errors](https://letmepost.dev/docs/errors/). contact: name: letmepost.dev url: https://github.com/rosekamallove/letmepost.dev license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.letmepost.dev description: Production security: - bearer: [] tags: - name: Posts description: >- Publish and read posts. Multi-target: a single `POST /v1/posts` fans out to up to 25 connected accounts. - name: Media description: Upload and reference media assets. - name: Accounts description: Connect, list, and disconnect platform accounts. - name: API Keys description: Mint and revoke API keys (dashboard session only). - name: Webhooks description: Register, test, and manage outbound webhook endpoints. paths: /v1/webhook-endpoints: post: tags: - Webhooks summary: Register a webhook endpoint description: >- Authenticated with an API key or dashboard session. The `signingSecret` is returned **once** at creation and is used to verify the HMAC-SHA256 `X-Letmepost-Signature` header on every delivery. An empty `events` array subscribes to every event type. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookEndpointRequest' example: url: https://hooks.example.com/letmepost events: - post.published - post.failed description: Production publish notifications. responses: '201': description: Endpoint created. `signingSecret` shown once. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointWithSecret' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthenticated' '409': $ref: '#/components/responses/IdempotencyConflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - bearer: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Recommended on every write. Replays within 24 hours return the original response; conflicting bodies surface as `409 idempotency_conflict`. See [Idempotency](https://letmepost.dev/docs/idempotency/). schema: type: string minLength: 1 maxLength: 128 example: post-launch-2026-05-15-001 schemas: CreateWebhookEndpointRequest: type: object required: - url properties: url: type: string format: uri example: https://hooks.example.com/letmepost events: type: array items: $ref: '#/components/schemas/WebhookEventType' default: [] description: Empty array subscribes the endpoint to every event type. description: type: string maxLength: 500 WebhookEndpointWithSecret: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: - signingSecret properties: signingSecret: type: string description: >- HMAC-SHA256 signing secret — returned **once** at creation. Used to verify every delivery's `X-Letmepost-Signature` header. example: whsec_… WebhookEventType: type: string enum: - post.queued - post.validated - post.published - post.rejected - post.failed - post.canceled - post.rescheduled - token.expiring - token.revoked - version.deprecated WebhookEndpoint: type: object required: - id - url - events - active - createdAt - updatedAt properties: id: type: string url: type: string format: uri events: type: array items: $ref: '#/components/schemas/WebhookEventType' description: type: - string - 'null' active: type: boolean lastDeliveryAt: type: - string - 'null' format: date-time lastFailureReason: type: - string - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time ApiError: type: object description: >- Stable error envelope. Every non-2xx response uses this shape. `docUrl` is always present; `ruleUrl` is present whenever `rule` is set. required: - error properties: error: type: object required: - code - message - docUrl - requestId properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable summary. Stable enough to log, not stable enough to switch on — switch on `code` and `rule`. rule: type: string description: >- The specific preflight rule or validator that failed (e.g. `bluesky.text.max_graphemes`, `targets.options.platform_mismatch`). example: bluesky.text.max_graphemes platform: $ref: '#/components/schemas/Platform' platformVersion: type: string description: >- Pinned upstream API version the call targeted (e.g. `graph-v23.0` for Facebook). platformResponse: description: Raw upstream platform response, when available. remediation: type: string description: Actionable next step for the caller — short, imperative. docUrl: type: string format: uri description: Link to the docs page for this `code`. example: https://docs.letmepost.dev/errors/preflight_failed ruleUrl: type: string format: uri description: >- Link to the docs page for this preflight `rule`. Present whenever `rule` is set. example: https://docs.letmepost.dev/preflight/bluesky-text-max_graphemes requestId: type: string description: >- Per-request correlation id, also echoed in the `X-Request-Id` response header. example: req_01HY6X4AWBJM2K9F2PTQMRD9JQ traceId: type: string description: OpenTelemetry trace id, when tracing is active. example: error: code: preflight_failed message: Bluesky posts are capped at 300 graphemes; this body is 312. rule: bluesky.text.max_graphemes platform: bluesky remediation: Trim 12 graphemes, or split into a thread. docUrl: https://docs.letmepost.dev/errors/preflight_failed ruleUrl: https://docs.letmepost.dev/preflight/bluesky-text-max_graphemes requestId: req_01HY6X4AWBJM2K9F2PTQMRD9JQ ErrorCode: type: string enum: - validation_failed - preflight_failed - platform_auth_failed - platform_rejected - platform_unavailable - platform_not_enabled - internal_error - unauthenticated - unauthorized - not_found - idempotency_conflict - rate_limited description: >- Canonical error codes. See https://letmepost.dev/docs/errors/ for per-code documentation. Platform: type: string enum: - bluesky - facebook - instagram - linkedin - pinterest - threads - tiktok - twitter description: >- Supported platforms. `tiktok` is currently in App Review — connect requests return `platform_not_enabled` until approval lands. headers: X-RateLimit-Limit: description: >- Per-route request ceiling for this endpoint. A static contract — sliding-window remaining/reset live on the IETF-draft `RateLimit-*` headers (no prefix) when enforcement is active. schema: type: integer minimum: 1 example: 1000 X-Request-Id: description: >- Per-request correlation id, also echoed inside the error envelope as `error.requestId`. schema: type: string example: req_01HY6X4AWBJM2K9F2PTQMRD9JQ responses: ValidationError: description: >- `validation_failed` — request body or query parameters didn't match the schema. Rules surfaced include `body.json`, `targets.required`, `targets.max`, `mode_conflict`, `targets.options.platform_mismatch`, `targets.account.platform_mismatch`, `target.account.not_connected`, `target.account.ambiguous`, `scheduledAt.future`, `scheduledAt.text_only`. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthenticated: description: '`unauthenticated` — missing or invalid Bearer key.' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' IdempotencyConflict: description: >- `idempotency_conflict` — the same `Idempotency-Key` was used with a different request body. Use a new key, or retry with the original body. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimited: description: >- `rate_limited` — too many requests. Inspect `X-RateLimit-Limit` (static ceiling) and the IETF-draft `RateLimit-*` headers (sliding-window remaining/reset) before retrying. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalError: description: >- `internal_error` — something on our end failed unexpectedly. Quote the `requestId` when reporting. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearer: type: http scheme: bearer bearerFormat: lmp_live_… or lmp_test_… description: >- Mint an API key in the dashboard. See https://letmepost.dev/docs/authentication/. ````