postlake-dev Webhooks API

openapi: 3.2.0
info:
  title: PostLake Webhooks API
  version: 1.0.0
  description: Unified social media API. One API key, 10 platforms, normalised responses. Built for agents and developers.
  contact:
    url: https://postlake.dev
servers:
- url: https://api.postlake.dev
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: Register and manage webhook endpoints
paths:
  /v1/webhooks:
    post:
      tags:
      - Webhooks
      summary: Register webhook
      description: Register a webhook endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/WebhookEventType'
              required:
              - url
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid URL or events
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postV1Webhooks
      x-operation-id-source: derived
    get:
      tags:
      - Webhooks
      summary: List webhooks
      description: List webhook endpoints
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
                required:
                - webhooks
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getV1Webhooks
      x-operation-id-source: derived
  /v1/webhooks/{id}:
    delete:
      tags:
      - Webhooks
      summary: Delete webhook
      description: Delete a webhook endpoint
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  deleted:
                    type: boolean
                required:
                - id
                - deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Webhook not found
      operationId: deleteV1WebhooksById
      x-operation-id-source: derived
  /v1/webhooks/{id}/test:
    post:
      tags:
      - Webhooks
      summary: Send webhook test event
      description: Sends one signed webhook.test event to this endpoint with a ten-second timeout. The receiver must return 2xx directly; redirects are not followed. A failed attempt enters the durable retry queue. HTTP success confirms receipt, not application processing.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivery attempted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Webhook not found
      operationId: postV1WebhooksByIdTest
      x-operation-id-source: derived
  /v1/webhooks/deliveries:
    get:
      tags:
      - Webhooks
      summary: List pending and dead-lettered deliveries
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - dead
      responses:
        '200':
          description: Retry-queue deliveries
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getV1WebhooksDeliveries
      x-operation-id-source: derived
  /v1/webhooks/deliveries/{id}/replay:
    post:
      tags:
      - Webhooks
      summary: Replay a webhook delivery
      description: Attempts the durably queued original event again without changing its event id, publishing content or charging credits. Generates a fresh signature. An active delivery lease returns 409 instead of starting an overlapping attempt. Post lifecycle notifications are persisted atomically with saved post state.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivery attempted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Webhook delivery not found
        '409':
          description: Delivery already has an active attempt
      operationId: postV1WebhooksDeliveriesByIdReplay
      x-operation-id-source: derived
components:
  schemas:
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        secret:
          oneOf:
          - type: string
          - type: 'null'
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - url
      - secret
      - events
      - createdAt
    WebhookEventType:
      type: string
      enum:
      - post.approved
      - post.rejected
      - post.published
      - post.failed
      - post.partial
      - post.processing
      - account.connected
      - account.disconnected
      - message.received
      - comment.received
      - mention.received
      - webhook.test
      description: Which events an endpoint wants. `message.received` currently fires for Facebook and Instagram, where Meta pushes new messages to PostLake. Its payload carries `replyBy`, the moment Meta stops accepting a normal reply. Poll list conversations for inbox-capable networks that do not provide PostLake with inbound message webhooks.
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NormalisedError'
      required:
      - error
    NormalisedError:
      type: object
      description: '`type` is the coarse category you route on and is deliberately small, so it cannot say WHICH input was wrong. `code`, `fix`, `docs` and `param` are what turn a rejection into something a caller can act on rather than guess at. They are optional only in the sense that not every error has all four.'
      properties:
        type:
          type: string
          description: Coarse category to route on, e.g. rate_limited, auth_expired, platform_rejected.
        message:
          type: string
        platform:
          oneOf:
          - $ref: '#/components/schemas/Platform'
          - type: 'null'
        retryable:
          type: boolean
        code:
          type: string
          description: Stable, granular handle to branch on, e.g. text_too_long. Also the anchor in the error reference.
        fix:
          type: string
          description: The next action, in plain words. Safe to show a person as-is.
        docs:
          type: string
          format: uri
          description: Where the rule is written down, so it is learned once rather than rediscovered.
        param:
          type: string
          description: The request field at fault, so a form can mark the right input.
      required:
      - type
      - message
      - retryable
    Platform:
      type: string
      enum:
      - bluesky
      - threads
      - x
      - linkedin
      - instagram
      - tiktok
      - facebook
      - youtube
      - pinterest
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: unauthorized
              message: missing or invalid api key
              retryable: false