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

# Register webhook endpoint

> Registers a URL to receive webhook events for the specified event types.

The response includes a `signingSecret` (base64-encoded, 32 bytes) that is
returned **once only**. Use it to verify the `X-Woop-Signature` header on
incoming webhook payloads.

**Signature format:** `t=<unix>,v1=<hmac-sha256-hex>`
**Signed payload:** `<unix>.<json-body>`




## OpenAPI

````yaml /openapi.yaml post /webhooks
openapi: 3.1.0
info:
  title: WoopSocial API
  version: 1.0.0
  summary: API for WoopSocial integrations.
  description: >
    This is the public-facing OpenAPI contract for WoopSocial. It supports
    scheduling posts for various social media platforms such as Facebook,
    Instagram, LinkedIn, LinkedIn Pages, Pinterest, Threads, TikTok, X (formerly
    Twitter) and YouTube.
servers:
  - url: https://api.woopsocial.com/v1
    description: WoopSocial API URL.
  - url: http://localhost:9123/api/external/v1
    description: Local WoopSocial API URL.
security: []
tags:
  - name: Posts
    description: Post scheduling endpoints.
  - name: Projects
    description: Project discovery endpoints.
  - name: Social Accounts
    description: Connected social account discovery endpoints.
  - name: Media
    description: Media upload endpoints.
  - name: Webhooks
    description: Webhook endpoint management.
  - name: Health
    description: Basic connectivity endpoints.
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Register webhook endpoint
      description: >
        Registers a URL to receive webhook events for the specified event types.


        The response includes a `signingSecret` (base64-encoded, 32 bytes) that
        is

        returned **once only**. Use it to verify the `X-Woop-Signature` header
        on

        incoming webhook payloads.


        **Signature format:** `t=<unix>,v1=<hmac-sha256-hex>`

        **Signed payload:** `<unix>.<json-body>`
      operationId: createWebhookEndpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointRequest'
      responses:
        '201':
          description: Webhook endpoint registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '422':
          description: Validation error (unknown event type, empty url, etc.).
      security:
        - ApiKey: []
components:
  schemas:
    CreateWebhookEndpointRequest:
      type: object
      required:
        - url
        - eventTypes
      properties:
        url:
          type: string
          description: The HTTPS URL to POST webhook events to.
        eventTypes:
          type: array
          description: Webhook event types this endpoint should receive.
          items:
            $ref: '#/components/schemas/WebhookEventType'
          minItems: 1
    WebhookEndpoint:
      type: object
      required:
        - id
        - url
        - eventTypes
        - createdAt
      properties:
        id:
          type: string
          description: Webhook endpoint identifier (int64 as string).
        url:
          type: string
        eventTypes:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
        createdAt:
          type: string
          format: date-time
        signingSecret:
          type: string
          description: >-
            Base64-encoded 32-byte signing secret. Returned once on creation
            only.
    WebhookEventType:
      type: string
      enum:
        - socialAccountPost.delivery.published
        - socialAccountPost.delivery.failed
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key

````