postproxy-dev Webhooks API

openapi: 3.2.0
info:
  title: Postproxy Social Media Webhooks API
  version: '2026-09-21'
  summary: Unified social media API for publishing, comments, direct messages, and reviews.
  description: 'The Postproxy API lets you programmatically create and manage social media posts across Facebook, Instagram, TikTok, LinkedIn, YouTube, X (Twitter), Threads, Pinterest, Bluesky, Telegram, and Google Business. Beyond publishing you can read and reply to comments, read and send direct messages, and reply to Google Business reviews and Facebook Page recommendations.


    Send one payload; Postproxy maps it to each platform''s rules and returns a per-platform outcome. Sandbox mode is included on all plans for development without real accounts.


    Human-readable reference: https://postproxy.dev/reference/overview/


    ## Versioning and deprecation


    The API has a single stable version served at https://api.postproxy.dev/api. Releases are identified by this document''s date-based `info.version`. Changes are additive: new endpoints, new optional parameters, and new response fields may appear, and clients should ignore fields they do not recognize. Existing fields, parameters, and status codes are not changed or removed without a deprecation cycle.


    When an endpoint or field is deprecated it is marked `deprecated: true` in this specification and announced in the changelog (https://postproxy.dev/getting-started/changelog/) at least 90 days before removal.'
  termsOfService: https://postproxy.dev/terms-conditions/
  contact:
    name: Postproxy Support
    url: https://postproxy.dev/developers/
    email: support@postproxy.dev
  x-versioning:
    strategy: stable-single-version
    spec-version-format: date (YYYY-MM-DD)
    compatibility: additive-only; breaking changes go through a deprecation cycle
    deprecation-signal: 'deprecated: true in this spec, plus a changelog announcement at least 90 days before removal'
    changelog: https://postproxy.dev/getting-started/changelog/
servers:
- url: https://api.postproxy.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Subscribe to post lifecycle and engagement events
  externalDocs:
    url: https://postproxy.dev/reference/webhooks/
paths:
  /api/webhooks:
    get:
      operationId: webhooks_list
      summary: List webhooks
      description: Retrieves all webhooks configured for your account.
      tags:
      - Webhooks
      externalDocs:
        url: https://postproxy.dev/reference/webhooks/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: webhooks_create
      summary: Create webhook
      description: Creates a webhook subscription. Save the secret from the response - it is only shown on creation and when fetching a single webhook.
      tags:
      - Webhooks
      externalDocs:
        url: https://postproxy.dev/reference/webhooks/
      parameters:
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - events
              properties:
                url:
                  type: string
                  description: HTTPS URL to receive webhook events.
                events:
                  type: array
                  description: Event types to subscribe to (use ["*"] for all).
                  items:
                    type: string
                description:
                  type: string
                  description: Description for the webhook.
      responses:
        '201':
          description: Webhook created (includes the signing secret)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/webhooks/{id}:
    get:
      operationId: webhooks_get
      summary: Get webhook
      description: Retrieves a single webhook. The secret field is only included when fetching a single webhook or immediately after creation.
      tags:
      - Webhooks
      externalDocs:
        url: https://postproxy.dev/reference/webhooks/
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      responses:
        '200':
          description: The webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: webhooks_update
      summary: Update webhook
      description: Updates a webhook's URL, subscribed events, enabled state, or description.
      tags:
      - Webhooks
      externalDocs:
        url: https://postproxy.dev/reference/webhooks/
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: New HTTPS URL.
                events:
                  type: array
                  description: New event types.
                  items:
                    type: string
                enabled:
                  type: boolean
                  description: Enable or disable the webhook.
                description:
                  type: string
                  description: Updated description.
      responses:
        '200':
          description: The updated webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: webhooks_delete
      summary: Delete webhook
      description: Deletes a webhook subscription.
      tags:
      - Webhooks
      externalDocs:
        url: https://postproxy.dev/reference/webhooks/
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Webhook deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/webhooks/{id}/deliveries:
    get:
      operationId: webhooks_deliveries_list
      summary: List deliveries
      description: Retrieve delivery attempts for a specific webhook, useful for debugging.
      tags:
      - Webhooks
      externalDocs:
        url: https://postproxy.dev/reference/webhooks/
      parameters:
      - name: id
        in: path
        required: true
        description: Webhook id
        schema:
          type: string
      - $ref: '#/components/parameters/ProfileGroupId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated list of delivery attempts
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookDelivery'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
        default: 10
    ProfileGroupId:
      name: profile_group_id
      in: query
      required: false
      description: Profile group context for the request. Optional when the API key is scoped to a profile group (that group is used automatically); with a full-access key, defaults to the first profile group in the account.
      schema:
        type: string
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional idempotency key (up to 255 characters; a UUID is ideal). Retrying a successful write with the same key replays the original response (with an Idempotent-Replay: true header) instead of executing again. Stored responses are kept for 24 hours; only 2xx responses are stored.'
      schema:
        type: string
        maxLength: 255
    Page:
      name: page
      in: query
      required: false
      description: Page number (1-based). Passing 0 returns page 1.
      schema:
        type: integer
        default: 1
        minimum: 0
  schemas:
    WebhookSubscription:
      type: object
      description: A webhook subscription that receives event deliveries at an HTTPS URL.
      properties:
        id:
          type: string
          description: Webhook id.
        url:
          type: string
          description: HTTPS URL that receives webhook events.
        events:
          type: array
          description: Subscribed event types (["*"] means all events).
          items:
            type: string
        enabled:
          type: boolean
          description: Whether the webhook is enabled.
        description:
          type: string
          description: Description for the webhook.
        secret:
          type: string
          description: Signing secret used to verify webhook signatures. Only included when fetching a single webhook or immediately after creation.
        created_at:
          type: string
          description: ISO 8601 creation time.
        updated_at:
          type: string
          description: ISO 8601 last update time.
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    WebhookDelivery:
      type: object
      description: A delivery attempt of a webhook event.
      properties:
        id:
          type: string
          description: Delivery record id.
        event_id:
          type: string
          description: Event delivery ID, prefixed with whevt_.
        event_type:
          type: string
          description: Event type delivered (e.g. post.processed).
        response_status:
          type: integer
          description: HTTP status code returned by the endpoint.
        attempt_number:
          type: integer
          description: Attempt number (deliveries are retried up to 5 times with exponential backoff).
        success:
          type: boolean
          description: Whether the delivery succeeded.
        attempted_at:
          type: string
          description: ISO 8601 time of the attempt.
        created_at:
          type: string
          description: ISO 8601 creation time.
  responses:
    Unauthorized:
      description: Invalid, missing, or insufficient API key permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidKey:
              value:
                error: Invalid API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key sent as a Bearer token in the Authorization header. Keys are either full-access (entire account) or scoped to a single profile group. Create keys at https://app.postproxy.dev under Settings → API Keys.
externalDocs:
  description: Full API reference
  url: https://postproxy.dev/reference/overview/