Derive Webhooks API

openapi: 3.2.0
info:
  title: Derive Webhooks API
  version: 1.0.0
  description: 'Derive''s HTTP API. Every response shape here is the single source of truth for the web client — generated from the same Zod schemas that back this reference, so the docs never drift from the running API.


    **Auth:** a session cookie (browser) or a bearer token (agents and the CLI). Most write routes are scoped to the caller''s active workspace. The `/v1` paths are the stable product surface; `/openapi.json` serves this spec and `/docs` renders it.'
tags:
- name: Webhooks
  description: Outgoing webhooks and their delivery log.
paths:
  /v1/webhooks:
    get:
      tags:
      - Webhooks
      summary: List the workspace's webhooks (Admin only)
      responses:
        '200':
          description: The workspace's webhooks, without their signing secrets, plus every event one can subscribe to — the server owns that list so the picker can't drift from it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                  event_options:
                    type: array
                    items:
                      type: string
                      enum:
                      - comment.created
                      - comment.mention
                      - comment.resolved
                      - version.published
                      - review.requested
                      - review.sent_back
                      - job.needs_you
                      - job.finished
                required:
                - webhooks
                - event_options
      operationId: getV1Webhooks
      x-operation-id-source: derived
    post:
      tags:
      - Webhooks
      summary: Create a webhook (Admin only)
      responses:
        '201':
          description: The created webhook, without its signing secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
      operationId: postV1Webhooks
      x-operation-id-source: derived
  /v1/webhooks/{id}:
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: The webhook was deleted.
      operationId: deleteV1WebhooksById
      x-operation-id-source: derived
  /v1/webhooks/{id}/deliveries:
    get:
      tags:
      - Webhooks
      summary: Recent delivery attempts for a webhook (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The 20 most recent delivery attempts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Delivery'
                required:
                - deliveries
      operationId: getV1WebhooksByIdDeliveries
      x-operation-id-source: derived
  /v1/webhooks/{id}/test:
    post:
      tags:
      - Webhooks
      summary: Send a sample event to a webhook so you can confirm it lands (Admin only)
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: The sample delivery was queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  queued:
                    type: boolean
                required:
                - queued
      operationId: postV1WebhooksByIdTest
      x-operation-id-source: derived
components:
  schemas:
    Delivery:
      type: object
      properties:
        id:
          type: string
        event_type:
          type: string
        status:
          type: string
          enum:
          - pending
          - delivered
          - dead
          description: 'Delivery state: pending (awaiting/retrying), delivered (succeeded), dead (gave up)'
        attempts:
          type: number
          description: Number of delivery attempts made so far
        last_error:
          type:
          - string
          - 'null'
          description: The most recent failure message, or null if none
        created_at:
          type: string
      required:
      - id
      - event_type
      - status
      - attempts
      - last_error
      - created_at
    Webhook:
      type: object
      properties:
        id:
          type: string
        artifact_id:
          type:
          - string
          - 'null'
          description: The artifact this webhook is scoped to, or null to fire on all workspace events
        url:
          type: string
          description: The destination endpoint deliveries are POSTed to
        kind:
          type: string
          enum:
          - generic
          - slack
          description: 'Delivery format: generic posts signed JSON, slack posts a Block Kit message'
        events:
          type: string
          description: Comma-separated event types to deliver, or "*" for all events
        label:
          type:
          - string
          - 'null'
          description: Optional human-readable label, or null if unnamed
        active:
          anyOf:
          - type: number
            enum:
            - 0
          - type: number
            enum:
            - 1
          description: Whether deliveries are enabled (1) or paused (0)
        created_at:
          type: string
      required:
      - id
      - artifact_id
      - url
      - kind
      - events
      - label
      - active
      - created_at