> ## Documentation Index
> Fetch the complete documentation index at: https://www.openpmm.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook Endpoint

> Create a webhook endpoint. The response contains the signing secret once. Full-content delivery also requires `posts:read`.



## OpenAPI

````yaml https://api.openpmm.com/v1/openapi.json post /workspaces/{workspace_id}/webhook-endpoints
openapi: 3.1.0
info:
  title: OpenPMM API
  version: 1.0.0
  description: >-
    Use one API to create and manage social posts. The signup operation does not
    need an API key. Other operations use an account API key. Workspace
    endpoints also use a workspace ID. Publishing requires explicit
    confirmation.
servers:
  - url: https://api.openpmm.com/v1
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Signup
    description: Create access to OpenPMM and the first workspace.
  - name: CLI Authorization
    description: Authorize the OpenPMM CLI through a browser sign-in.
  - name: Posts
    description: Create and manage posts.
  - name: Analytics
    description: Read and refresh current post analytics.
  - name: Assets
    description: Upload and manage media files.
  - name: Destinations
    description: Connect and manage social accounts.
  - name: Account
    description: Get account details and list available workspaces.
  - name: Billing
    description: Manage the account subscription and payment details.
  - name: Workspaces
    description: Create and manage workspaces.
  - name: Feedback
    description: Send product feedback to OpenPMM.
  - name: Team
    description: Manage account members and invitations.
  - name: Slack Notifications
    description: Configure Slack notifications.
  - name: Webhooks
    description: Configure signed post status events.
paths:
  /workspaces/{workspace_id}/webhook-endpoints:
    post:
      tags:
        - Webhooks
      summary: Create Webhook Endpoint
      description: >-
        Create a webhook endpoint. The response contains the signing secret
        once. Full-content delivery also requires `posts:read`.
      operationId: createWebhookEndpoint
      parameters:
        - name: workspace_id
          in: path
          required: true
          description: Unique workspace ID.
          schema:
            type: string
            example: ws_01JABCDEF
        - $ref: '#/components/parameters/OpenPMMRequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        $ref: '#/components/requestBodies/CreateWebhookEndpoint'
      responses:
        '201':
          description: The endpoint and its new signing secret.
          headers:
            OpenPMM-Request-Id:
              $ref: '#/components/headers/OpenPMMRequestId'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointSecret'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    OpenPMMRequestId:
      name: OpenPMM-Request-Id
      in: header
      required: false
      description: >-
        Optional request ID. OpenPMM returns this value when it is valid.
        Otherwise, OpenPMM creates a request ID.
      schema:
        type: string
        maxLength: 128
      example: req_01JABCDEF
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        A unique key for this operation. Use the same key when you retry the
        same request. Different input with the same key returns `409`.
      schema:
        type: string
        minLength: 1
        maxLength: 200
      example: 01J4Z3Y6K2M8V7C1N5Q9R0T4XA
  requestBodies:
    CreateWebhookEndpoint:
      required: true
      description: Webhook endpoint configuration.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateWebhookEndpointRequest'
          example:
            name: Production events
            url: https://example.com/openpmm/events
            event_types:
              - post.published
              - post.failed
              - post.awaiting-provider
              - post.needs-attention
            destination_filter_mode: all
            content_mode: metadata
  headers:
    OpenPMMRequestId:
      description: Stable identifier for this request.
      schema:
        type: string
    ETag:
      description: The current resource version for conditional updates.
      schema:
        type: string
    WWWAuthenticate:
      description: Bearer authentication challenge.
      schema:
        type: string
      example: Bearer realm="openpmm"
    RetryAfter:
      description: Number of seconds to wait before you retry the request.
      schema:
        type: integer
        minimum: 1
  schemas:
    WebhookEndpointSecret:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          example: wh_01JABCDEF
          description: Unique webhook endpoint ID.
        object:
          type: string
          const: webhook_endpoint
        name:
          type: string
        url:
          type: string
          format: uri
          description: Full webhook delivery URL.
        enabled:
          type: boolean
        event_types:
          type: array
          items:
            type: string
            enum:
              - post.published
              - post.failed
              - post.awaiting-provider
              - post.needs-attention
        destination_filter_mode:
          type: string
          enum:
            - all
            - selected
        destination_ids:
          type: array
          items:
            type: string
            example: dest_01JABCDEF
            description: Unique destination ID.
        content_mode:
          type: string
          enum:
            - metadata
            - full
        secret_last_four:
          type: string
          minLength: 4
          maxLength: 4
        previous_secret_expires_at:
          anyOf:
            - type: string
              format: date-time
              example: '2026-08-09T12:00:00.000Z'
            - type: 'null'
        config_version:
          type: integer
          minimum: 1
        created_at:
          type: string
          format: date-time
          example: '2026-08-09T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-08-09T12:00:00.000Z'
        secret:
          type: string
          readOnly: true
          description: Signing secret. This value is returned only once.
      required:
        - id
        - object
        - name
        - url
        - enabled
        - event_types
        - destination_filter_mode
        - destination_ids
        - content_mode
        - secret_last_four
        - previous_secret_expires_at
        - config_version
        - created_at
        - updated_at
        - secret
    CreateWebhookEndpointRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        url:
          type: string
          format: uri
          pattern: ^https://
          maxLength: 2048
          description: >-
            Public HTTPS URL. Use port 443 and a DNS hostname. Do not include
            credentials. The hostname must not resolve to a private or reserved
            address.
        enabled:
          type: boolean
          default: true
        event_types:
          type: array
          items:
            type: string
            enum:
              - post.published
              - post.failed
              - post.awaiting-provider
              - post.needs-attention
          minItems: 1
          uniqueItems: true
        destination_filter_mode:
          type: string
          enum:
            - all
            - selected
          default: all
        destination_ids:
          type: array
          items:
            type: string
            example: dest_01JABCDEF
            description: Unique destination ID.
          maxItems: 100
          uniqueItems: true
          default: []
        content_mode:
          type: string
          enum:
            - metadata
            - full
          default: metadata
      required:
        - name
        - url
    Problem:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
          example: Request failed
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        instance:
          type: string
          format: uri
        code:
          type: string
          example: public_invalid_request
        category:
          type: string
          enum:
            - authentication
            - authorization
            - billing
            - conflict
            - internal
            - not_found
            - provider
            - rate_limit
            - validation
        request_id:
          type: string
          example: req_01JABCDEF
        retryable:
          type: boolean
        retry:
          type: object
          additionalProperties: false
          properties:
            safety:
              type: string
              enum:
                - safe
                - not_retryable
            after:
              anyOf:
                - type: integer
                  minimum: 0
                - type: 'null'
          required:
            - safety
            - after
        user_action:
          type: string
          enum:
            - check_request
            - contact_support
            - inspect_resource
            - reauthorize
            - retry
            - wait
        reason:
          type: string
          enum:
            - velocity
            - backlog
            - account-paused
        retry_at:
          anyOf:
            - type: string
              format: date-time
              example: '2026-08-09T12:00:00.000Z'
            - type: 'null'
        provider_requests_started:
          type: boolean
          const: false
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ProblemError'
      required:
        - type
        - title
        - status
        - detail
        - instance
        - code
        - category
        - request_id
        - retryable
        - retry
        - user_action
        - errors
      description: RFC 9457 problem details with stable OpenPMM fields.
      example:
        type: https://www.openpmm.com/docs/reference/errors#public_invalid_request
        title: Invalid request
        status: 400
        detail: The request body does not match the public contract.
        instance: urn:openpmm:request:req_01JABCDEF
        code: public_invalid_request
        category: validation
        request_id: req_01JABCDEF
        retryable: false
        retry:
          safety: not_retryable
          after: null
        user_action: check_request
        errors:
          - pointer: /posts/0/destination_id
            code: custom
            detail: Publishing an entry requires a destination.
    ProblemError:
      type: object
      additionalProperties: false
      properties:
        pointer:
          type: string
          example: /posts/0/destination_id
          description: JSON Pointer to the invalid request member.
        post_id:
          type: string
          example: send_01JABCDEF
          description: Unique Post ID.
        code:
          type: string
          example: custom
        detail:
          type: string
          example: Publishing requires a destination.
        channel:
          type: string
          enum:
            - bluesky
            - facebook
            - instagram
            - threads
            - mastodon
            - x
            - linkedin
            - tiktok
            - youtube
          example: x
        destination_id:
          anyOf:
            - type: string
              example: dest_01JABCDEF
              description: Unique destination ID.
            - type: 'null'
        destination_label:
          type: string
        asset_id:
          anyOf:
            - type: string
              example: ast_01JABCDEF
              description: Unique asset ID.
            - type: 'null'
        property:
          type: string
        media_kind:
          type: string
          enum:
            - image
            - video
        actual:
          anyOf:
            - $ref: '#/components/schemas/MediaMeasure'
            - type: 'null'
        required:
          $ref: '#/components/schemas/MediaRequirementSummary'
        allowed_actions:
          type: array
          items:
            type: string
            enum:
              - replace_asset
              - remove_destination
              - retry
        retryable:
          type: boolean
      required:
        - code
        - detail
    MediaMeasure:
      oneOf:
        - type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              const: number
            value:
              type: number
            unit:
              type: string
          required:
            - kind
            - value
            - unit
        - type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              const: text
            value:
              type: string
          required:
            - kind
            - value
        - type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              const: boolean
            value:
              type: boolean
          required:
            - kind
            - value
    MediaRequirementSummary:
      oneOf:
        - type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              const: range
            min:
              anyOf:
                - type: number
                - type: 'null'
            max:
              anyOf:
                - type: number
                - type: 'null'
            unit:
              type: string
            owner:
              type: string
              enum:
                - openpmm
                - provider
                - destination
          required:
            - kind
            - min
            - max
            - unit
            - owner
        - type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              const: allowed
            allowed:
              type: array
              items:
                type: string
            owner:
              type: string
              enum:
                - openpmm
                - provider
                - destination
          required:
            - kind
            - allowed
            - owner
        - type: object
          additionalProperties: false
          properties:
            kind:
              type: string
              const: expected
            expected:
              type: string
            owner:
              type: string
              enum:
                - openpmm
                - provider
                - destination
          required:
            - kind
            - expected
            - owner
  responses:
    BadRequest:
      description: The request has invalid syntax, content, a cursor, or a header.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthenticated:
      description: Bearer authentication is missing or invalid.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
        WWW-Authenticate:
          $ref: '#/components/headers/WWWAuthenticate'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: The credential lacks the operation’s required scope.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: >-
        The resource does not exist, or the API credential cannot use its
        workspace.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: >-
        The request conflicts with the current state. This error also occurs
        when different input uses an existing idempotency key or when OpenPMM
        cannot determine the result of an earlier request.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            idempotency_outcome_unknown:
              summary: The result of an earlier request is unknown
              value:
                type: >-
                  https://www.openpmm.com/docs/reference/errors#public_idempotency_outcome_unknown
                title: Mutation outcome unknown
                status: 409
                detail: >-
                  The earlier request outcome is unknown. Inspect the affected
                  resource before you create new work.
                instance: urn:openpmm:request:req_01JABCDEF
                code: public_idempotency_outcome_unknown
                category: conflict
                request_id: req_01JABCDEF
                retryable: false
                retry:
                  safety: not_retryable
                  after: null
                user_action: inspect_resource
                errors: []
            post_group_channel_conflict:
              summary: The group already contains the requested channel
              value:
                type: >-
                  https://www.openpmm.com/docs/reference/errors#public_post_group_channel_conflict
                title: Request conflict
                status: 409
                detail: >-
                  This group already contains a draft Post for one or more
                  requested channels. Update or publish the existing draft
                  before you create another one.
                instance: urn:openpmm:request:req_01JABCDEF
                code: public_post_group_channel_conflict
                category: conflict
                request_id: req_01JABCDEF
                retryable: false
                retry:
                  safety: not_retryable
                  after: null
                user_action: check_request
                errors: []
    PayloadTooLarge:
      description: The request body exceeds the 1 MiB edge limit.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: >-
              https://www.openpmm.com/docs/reference/errors#public_payload_too_large
            title: Payload too large
            status: 413
            detail: The request body exceeds the 1 MiB limit.
            instance: urn:openpmm:request:req_01JABCDEF
            code: public_payload_too_large
            request_id: req_01JABCDEF
            retryable: false
            errors: []
    RateLimited:
      description: The request exceeded the rate limit.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        text/html:
          schema:
            type: string
    InternalError:
      description: OpenPMM could not complete the request because of an internal error.
      headers:
        OpenPMM-Request-Id:
          $ref: '#/components/headers/OpenPMMRequestId'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OpenPMM API key
      description: 'Send an account API key in the `Authorization: Bearer <key>` header.'

````